Tools

MadCap Flare Beats The Dinosaur

A slew of presentations and demos, in-depth discussions, Q&As with the sales and marketing guys from various vendors, in-house discussions, and we decided to go for MadCap Flare.

The MadCap Arrives

The D-day arrived and so did MadCap! We welcomed it with open arms to harness the power of XML. It also promised relief from some small-but-nonetheless-important annoyances of FrameMaker (FM). The only discomfort was the impending onerous task of migrating tons of documentation from the good ol' FM to Flare.

The Dinosaur Makes Way

FM had to step down. It felt a tad sad, I am sure. So did we. It had been with us through thick and thin, but mostly through thin.

The FM docs had to undergo a surgical migration. They had to be prepped and draped. Here it helped to understand the fundamental difference between Flare and FM, and the way both treat content.

Smallest Unit of Content

FM treats your manual as a book that contains many chapters. The chapters exist as individual files inside a book, thereby making the chapter or the file the smallest unit of content in Frame. On the other hand, Flare consists of tables of content (TOCs) and topics that make up the TOC; thereby, making the topic the smallest unit of content in Flare.

It then goes without saying that the topic should be self sufficient, and not depend on preceding topics for its existence.

An entire FM chapter can exist as a topic, but that defeats the purpose of topic-based modularity and reuse.


Analyzing FM Files 

An entire FM chapter can exist as a topic, but that defeats the purpose of topic-based modularity and reuse.

Before FM could pour its content into Flare seamlessly, we had to ensure that a few things worked flawlessly and correctly to reduce post-processing headaches in Flare.

• Deleting conditional text tags in FM: If there are any unused condition tags in FM, make sure you get rid of them before you migrate the content. Also, unhide all hidden content. 
• Checking application of defined styles: involves checking if defined styles were used wherever required, and removing any manually applied local character or paragraph styles. Also, you must ensure that paragraph, character, and table formats are applied consistently throughout, and also ensure deleting any unused formats.
• Checking file name, x-ref, topic alias markers: Checking whether all the H1s had unique file name markers, because after an analysis of our FM files, we found that it would be best to use H1s as our "New Topic Style". After importing, it is these file name markers that the topic files take on as names. We haven't touched topic alias markers in our migration, so I cannot comment on that bit. You must update all x-refs and ensure that the targets exist within the FM project.
• Checking for logical structure: Checking whether all H1s contain the same kind of information, and vice versa, that is checking whether the same kind of information is being tagged similarly.

        For example,
        - <H1>Creating Contracts</H1>
        - <H1>Editing Contracts</H1>
                - <H2>Editing Contracts Online</H2>
                - <H2>Editing Contracts Offline</H2>
        - <H1>Presenting Contracts</H1>
        - <H1>Negotiating Contracts</H1>
        - <H1>Executing Contracts</H1>
        - <H1>Amending Contracts</H1>

• Checking cross-references and targets: Checking whether all cross-references work and can find their target files.
• Updating and formatting FM TOCs: Checking whether all the headings that you want as a part of the Flare TOC are first a part of the FM TOC. (Run update book command in FM before you import the files to Flare). Also, ensure that your TOC entries are indented or nested properly in FM before you import or you will end up with a flat Flare TOC (with all TOC entries at the same level).

Note: Though we haven't used any, there are tools in the market that help you prep your FM files for migration. The more time you spend understanding your FM files setup, and fixing any inconsistencies that you see, the better will be your results after the import.


Working With Flare During the Import Process

Flare has a handy wizard to help you every step of the way. You can import .book, .fm, or .mif files into Flare. For the very first import, it is advisable to import FM books into Flare so that Flare gets access to all the documents that are associated with the book. Later on, when you have a Flare project in place, you may want to import individual FM files, if the need arises. During the import, you can select an option to keep the Flare files linked to the FM source files. This is useful if you plan to still continue using your FM as the authoring tool, and use Flare only for rendering outputs. In such cases, every time you access this Flare project, you are asked to re-import content from FM if the source has been updated after the last import.

    During the import process, you must make a few critical decisions such as:

•     Which FM style to map to which new topic style in Flare?
•     How to deal with long topics?
•     What should be the cross-reference format?
•     Whether to avoid creating empty topics?
•     What should be the word count threshold to avoid creating empty topics?
•     Whether and which stylesheet to use?
•     Whether to preserve FM styles; if yes, what will be the conversion styles?
•     What one-to-one paragraph style mapping to use between FM and Flare styles?
•     What one-to-one character style mapping to use between FM and Flare styles?
•     Whether to generate images from anchored frames?
•     Whether to preserve image size to be the same as that in FM?
•     What should be the maximum allowed topic file name length?
•     Whether to allow passthrough markers, and if yes, what is to be the passthrough marker format: text, fragment, or XML?
•     Whether to auto-reimport every time before generating the output?
•     Whether to convert table styles?
•     What one-to-one paragraph style mapping to use between FM and Flare styles?
•     What one-to-one character style mapping to use between FM and Flare styles?
•     What cross-reference style mapping to use between FM and Flare styles?

These decisions you make are stored as "import rules" in a file.If you want to make any changes to these rules, you simply have to open the relevant import file from Project Organizer > Imports, make the changes you want, and then reimport the files once again to reflect your changes.



Post-Import Processing

Once your content is in Flare, you still cannot heave a sigh of relief! You must visually inspect the import, and make decisions about which files you want to accept and which you wish to decline. If this is the first-ever import from FM to Flare, you will not see any information about the differences in existing files in FM and Flare. However, when you re-import, Flare gives you information about whether the file in your Flare project is newer or the one that has been reimported is newer. You can decide which file to keep - the local or the source.

It is a good idea to generate both HTML and PDF outputs of your projects to see if everything displays correctly and the way you want it to. You may have to reimport files that don't display correctly or edit the stylesheet, as the situation demands.

Now, we are working with the new monkey that has some great features when compared to the dinosaur. Enough for today (as Osho always said after his discourses ;-)). That makes a topic for another post. So stay tuned in, and I'll be back with more.

Enough for today!