Do you work on a documentation team that needs to import thousands of pages of legacy FrameMaker® documentation into MadCap Flare? It may seem like a daunting task, but there are several steps you can follow that will make life much easier for you if you happen to be the writer tasked with this project. The following are some of my best practices for importing FrameMaker® documentation into Flare.

Build Your Style Sheet Before Importing

I can’t recommend this step highly enough. In my experience, there was always some reformatting that needed to be done after importing FrameMaker® files. If your style sheet is not built or if you are constantly making changes to it throughout the import process, it is only going to add more work for you in the long run.

Create a Flare Project Template

If you are importing your FrameMaker® documentation into several Flare projects, consider creating a project template. Creating a project template helps you keep a consistent look and feel across your Flare projects. Project templates are especially helpful if you have more than one writer working on the FrameMaker® import project. Consider including the following items in your template project:

  • Page layouts for your front matter, chapter pages, and index
  • The style sheet you will be using for your Flare projects
  • Targets built for the types of outputs you will be using
  • Master pages
  • Skins
  • Variable sets
  • TOCs (to be used as placeholders for your actual TOCs)

Decide the Heading Levels at Which to Break Topics

During the FrameMaker® import process, Flare will ask you to specify the heading levels at which you are going to break your topics. Therefore, it’s best to make a decision on this ahead of time. In my experience, I broke the topics at heading levels 1 and 2 to cut down on the total number of topics that were created. If you decide after importing that you need to break the topics at additional heading levels, you can always re-import the files and specify the new heading levels at which you want to break your topics. Keep in mind that the more heading levels you break topics at, the more topics you will ultimately be working with.

Establish a Topic Naming Convention Once the Files are Imported into Flare

When Flare imports the FrameMaker® documentation into individual topics, it automatically gives them a name. Having a naming convention set up ahead of time will enable you to rename your topics in a way that is acceptable to other team members/users of the project.

Once You Import the FrameMaker® Files, Set Up the Flare Project Framework Before Working on Topics

If you have already created a Flare project as I suggested, this will be a quick and easy step. You will simply need to update the information in your master pages, targets, and so forth to match the document that you’ve just imported. If not, you will need to add page layouts, style sheet(s), master pages, targets, TOC placeholders, variable sets, and skins to your Flare project and update them to match the information in the FrameMaker® document you just imported.

Use the TOC from Your FrameMaker® Manual to Build Your TOC in Flare

I found this to be an easy way to build TOCs in Flare. I would simply print the TOC from the FrameMaker® manual and use it as a guide to build my TOC in Flare.

Create Separate TOCs for Print and Online Outputs

If you are going to be using both print and online outputs, I recommend that you create two TOCs – one for print outputs and one for online outputs. I recommend you build your print TOC first, use Flare’s Save As function to save it as your online TOC, and remove the topics you don’t need for your online TOC (such as cover page, front matter, and so forth).

Final Clean Up

The final steps you will want to take to finish the import process are as follows:

  • Rename bookmarks (to something that will make them easier to work with)
  • Rename topic files (as necessary)
  • Add concept and index tags (as necessary)
  • Reformat topics (as necessary)
  • Update cross references (as necessary)

Once you complete all of the above steps, you should be ready to start generating your outputs and testing them to make sure they look as they should.

Conclusion

Importing FrameMaker® documents into Flare can be a time consuming and challenging process but by setting up your framework ahead of time and following the steps outlined above, you can make life a lot easier on yourself and speed up your import times. See you in the trenches!