I like the way Flare help uses organizational pages in its help system to organize content into a process. You can learn “About Indexing,” and within that topic, you can click drop down links to display a description of the Index Entry pane. You can click another drop down link to see the steps for adding an index entry, and so on. I think things are set up pretty well in the system, now I’m just ready for some important information to be added within that structure.
In particular, print documentation brought with it several points of pain. Importing it, outputting it, formatting CSS for it. Over the course of our Flare implementation, as my knowledge of help authoring concepts and technical skills have progressed, I have found that Flare help does have information that I would have sworn a few months ago was not in there. Of course, that’s because I have provided the context for myself. Now that I know how the bits of information needed for print imports and targets work together, I can find most of them in the help system.
Here is an overview of importing legacy Word documents that I hope will find folks that were where I was six months ago:
- Creating the project.
Our team has a set of common files that has grown over time to include master pages, a set of topics about the help system, condition sets. The first shared file, which we produced as soon as we could, was the department CSS. Another important set of shared topics is the standard preface for our user manual. Since this is where we use the two master pages that supplement our main master page, it’s important that everyone had that content split into topics in the same way We keep these common files in a master project on our server. I’m curious how other teams handle common files.
- Creating the folders in the Content Explorer.
These are the folders where you access the topics to edit them, and their organization should be somewhat standard across projects, in my opinion. I also recommend that they mirrored the structure/TOC of the legacy content. I added these folders prior to importing legacy documents so that I could sort the imported content into the appropriate folders quickly. If you’re just sorting the topics that are created during import into the same chunks, or chapters, that you were accustomed to them being in, you can reduce the time it takes to produce your first set of outputs.
- Dividing the legacy manual into separate Word documents.
That way the topics created by each import could be easily sorted into the CE folders. For example, a Word doc for every chapter, then break each chapter down into a Word doc for every section of the chapter. In our case, a section consisted of a set of procedures and a set of reference items. Since headings for each information type were distinct and standardized (gerunds for procedures, ‘such-and-such description’ for reference), once I had a Word document for each section I could easily sort the resulting topics into the CE folders.
- Preparing each document for import.
Depending on how well your imported docs play with Flare, you may want to remove cross-references, page breaks, section breaks, or logo pages before you import. You can test-import a document or two to see what doesn’t come over well.
- Creating a CSS with styles that corresponded to the styles in the Word template.
Your imported content is formatted by a template, right? This decision saved us from having to design a CSS from scratch. It also saved us from having to debate a revamp of our styles—if it was in our Word template it went in our CSS. For the first version of the CSS, that was the end of the discussion. You can create a CSS based on your Word styles by specifying that Flare create those CSS styles during import and then refining the results. I don’t think this is what our CSS guy did, though.
- Mapping Word styles to the corresponding CSS styles during import.
I did this for each style that I could. You can’t map to list styles, though (at least not in 3.1). This was really too bad, considering how much of our content was procedures. If any one has a guess as to why this wasn’t done, I’d be interested in such a speculation.
- Formatting imported content.
Imported lists all had to be combined, because imported list displayed each list item as a separate list. Imported tables didn’t use table styles if there was a paragraph break in the cell. No biggie, except some cells didn’t have paragraph breaks, and so used table styles. Many links and cross references were broken and so were only serving as placeholders for corrections. Many of our images were stripped out or placed in the wrong location.
- Creating TOCs that mirrored the structure of the imported content.
This is the same idea as I mentioned in regards to the Content Explorer. I made my TOC match the manual that I imported. This resulted in quick turnaround for the first iteration, and that means I had more time in the second iteration to design how I wanted the help content to vary from that structure.
- Formatting each style for online and print.
Flare lets us specify a medium for each of our CSS styles—make h1 look Fuschia and 18 point online while it remains a prim and proper black for print targets. Another reason why you don’t have to rearrange content or styles much for your first iteration—leave the same style applied; just change its appearance according to the medium.
- Retaining heading numbers.
This concept of working your CSS mediums was most helpful for headings. For us, headings 1-5 generated new topics during import. As a result, the most common first heading for a topic was heading 5. This did not look beautiful for online topics. At the same time, we didn’t want to have to try and reapply the correct styles when our topics got back together again in a Word target. So, we formatted headings 1-5 all the same for online medium. They all looked like heading 1. Then we formatted them uniquely for print.
Please do let me know if you have a tip for importing to share!
