Importing Word documents into Flare

When organisations first adopt MadCap Flare, they frequently have legacy documentation stored in Microsoft Word format. One of their first tasks, therefore, is to migrate that documentation, and I am often asked for help with importing Word documents into Flare. This is a task that should not be underestimated — although Flare is able to automate the import process to a large degree, there is typically a large amount of pre-import preparation of the Word documents and post-import clean-up of the resulting Flare content required.

In my 2014 article Importing from MS Word into MadCap Flare, I described in detail the steps for importing Word documents into Flare. However, the workflow and user interface has changed significantly since then — especially in the 2019 r2 release, when the Word Import Editor was completely restructured. That release also introduced the ability to drag and drop Word documents into Flare, which I covered in the Winter 2019 issue of Communicator.

In this article, I provide some tips on the best options to select within the restructured Word Import Editor. I will focus on the options relating to styles because my aim is for the resulting imported content to be marked up in the cleanest and most consistent possible way within Flare.

Starting the Word import process

There are several different ways of starting the Word import process, including:

• Creating a new Flare Project from MS Word Documents,
• Using the Import Microsoft Word Wizard (by selecting from the Project ribbon Import > MS Word Documents), or
• Dragging and dropping a Word document from the Windows File Explorer into Flare.

My own personal preference is to start the process by adding a new MS Word Import File within the Project Organizer's Imports folder (see screenshot below), which all the other methods actually do behind the scenes anyway.

Whichever method you choose, this is just the start of the process, and there are several options that need to be configured correctly within either the Word Import Editor or the Import Microsoft Word Wizard. The options are actually the same in each case, and I'll offer some tips on them in the following sections.

Create new styles or map to existing styles?

Some authors use the Word import process as a way of creating a new stylesheet in Flare that replicates the formatting within the original Word document. Personally, I prefer to map the Word styles to styles that I am already using within Flare. My two main reasons for this are:

• I don't necessarily want to use the same formatting for the content in Flare as it had in the original Word document — I would rather the imported content matched the format of other content within the same Flare project
• The stylesheet created by the import process typically contains a lot of redundant CSS code, and does not make use of important CSS techniques such as inheritance, complex selectors, or pseudo classes. I can usually do a better job of crafting a stylesheet myself using my knowledge of CSS, or I can choose to use one of the many sample stylesheets available within the project templates supplied by MadCap Software.

To map the styles, you must choose to associate a stylesheet — this means selecting an existing stylesheet that contains the styles you want to map to. If you are importing into an existing project (as I usually am), the stylesheet you select does not have to be already within the current project — it can be anywhere on your computer or local network. If you do select a stylesheet that is within the current project, it will be modified as a result of the import. For that reason, I choose to use an external stylesheet that contains the same style names as my project's Primary Stylesheet, but with a different filename (to avoid overwriting the Primary Stylesheet). As a result, my Primary Stylesheet will be untouched by the import process.

I then proceed to click the Discard MS Word Styles button, and map each of the styles from the Word document to the best corresponding style within the selected Flare stylesheet. This screenshot shows some typical mappings:

Note that I have mapped all headings that will become new topics to the h1 style, since that is the style I always use for topic headings in Flare.

Tips for configuring the Advanced Options

Whether you are using the Import Microsoft Word Wizard or the Word Import Editor, there is a tab containing Advanced Options that enables you to control some key aspects of the conversion process. This screenshot shows how these options are presented within the Word Import Editor:

I recommend selecting the option to Create new stylesheet, otherwise Flare may modify your project's existing stylesheet. I will usually delete the resulting new stylesheet after completing the Import (see below for more on this).

I usually choose to Remove inline formatting, which results in the cleanest mark-up within the imported topics. This may mean, however, that I will have to use Flare's XML Editor to add some formatting back into the imported topics by applying character styles to selected text where necessary.

I also recommend selecting Automatically set topic title, which simply means that Flare will leave empty the Topic Title field in the Properties of each topic. As a result, the Topic Title will be automatically set to the first heading in each topic.

Regarding tables, I usually recommend selecting both the following options:

• Convert all tables to "auto-fit to contents" — this removes the width property from the table. If you don't do this, the table will be assigned a fixed width matching the original table in the Word document, which results in the table being less responsive in Flare.
• Set first row of each table as a header row — if you don't select this, all rows will be formatted as normal table body rows (even if the first row was a header row in the original Word document).

You may also find it useful to choose Apply a table stylesheet to all imported tables (and then select the required table stylesheet). However, in my experience this option does not always work correctly if you have selected Remove inline formatting (as recommended above). As an alternative, after the import you can apply a table stylesheet to the tables in all the imported topics by using the Apply Style button in the TableStyle Editor. For more information on this feature, see How to Apply a Table Stylesheet—Multiple Tables and Files.

Post-import tasks

After completing the import, if I have mapped to an external stylesheet with a different name from my Primary Stylesheet, this stylesheet will have been copied into my project, and all the imported topics will be linked to it. I see no reason for the topics to be linked in this way, and would prefer them simply to use my project's Primary Stylesheet so that they are formatted consistently with other topics in the project. For that reason, I usually delete the new stylesheet that resulted from the import, and remove the links from all the imported topics (see screenshot below).

Other post-import tasks that I recommend include:

• Checking the formatting of all new topics, and applying styles where necessary.
• Correcting the structure of multi-level lists by indenting items to the correct level.
• Removing any inline formatting that may be present within lists.
• Changing the labels of TOC items to use a variable (System.LinkedTitle or System.LinkedHeader) instead of plain text.

Conclusion

The process of importing legacy Word documents into Flare should be carefully planned, with plenty of time set aside to prepare the Word documents and clean up the imported Flare topics. By selecting the best options within the Word Import Editor to suit your needs, you can significantly improve the mark-up and structure of the resulting topics, and reduce the amount of clean-up required.