10 Steps for Importing Large Legacy Word Docs into Flare

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:

1. 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.
2. 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.
3. 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.

 

4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. 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!

Ode to our Word Template

Sometimes I just want to squeeze our chapter template like some old friend who has said something cute. It’s got so many redeeming qualities:  hanging indents, keep with next, keyboard shortcuts, macros. And it’s mature, so almost any style you could want is in there. If you do need to add a little something, it’s only a hop, skip, and a jump. What?

Seriously, the more I learn about tech comm, the more impressed I am with the woman who developed our template. When we watched some DITA demos a while back and researched structured authoring in preparation for updating help systems, information types and chunking turned out to be old hat. Procedures and reference material? We got that. Strategically-placed context information? Check. Man, were we spoiled.

Well, our template has some parting gifts for us. It just so happens that our Word template has been around and has seen some imports into a help authoring tool. I suspect that was a major function of the design, in fact. Standards for heading verbiage (gerunds for procedures, full window names for window descriptions) help us quickly sort imported content. Consistent organization of information types provides a ready-made TOC that works just fine in the help system. It seems obvious, but I can really tell the difference between our new help systems that folks have built from scratch and those that were composed from imported user manuals.

It’s the organization of information types, or chunking, that I have really relied on to quickly produce help from legacy Word manuals. I think clues like a consistently organized TOC and reliable topic titles help the user to navigate. We can have a good idea of what a topic covers without having to open it. For example; if we didn’t use those gerunds, Add New Record could be menu option rather than a task. 

Similarly, when I use a help system TOC, I expect that all non-expanded nodes in a book are on the same organizational level. Then when I expand one of those, all of the nodes displayed under it are then at a lower level and the same level as each other. If I start out not knowing where to find what I’m looking for, this helps me to be confident that I’ve narrowed it down as I progress. For example, let’s say I’m looking for how to add a Widget. Actually, I’m pretty sure I need to add a Widget, but there might be a better way to accomplish my task. I’m open to the possibility that what I may need to do is amend a Widget. So I start browsing the TOC. If the heading levels are not consistent—if I start drilling down in the Widget section and I don’t trust the organization, I start feeling anxious. Even if I think I have my answer I might have to go back a level and open all the Widget books to be sure I found the best way to accomplish my task.

The plug-and-play TOC has saved me hours–there are so many ways to relate our topics to each other, and it will be fascinating and worthwhile to revisit that organization, but not while I’m learning to use Flare and importing several hundred topics, thank you very much. For these first iterations, I just use the structure laid out in our user manuals.

So I’ll be a little sad to see our old template go. I argued to get it updated (before any of us really tried to build Word targets, we thought CSS would take care of everything) and I’m keeping it around for post-Flare processing. Sooner or later, though, Flare will fix the master page bugs and give us PDFs with bookmarks, and we’ll have all the legacy content imported. The template will be one more extra step that we shed as we race toward ROI. For now, the Word template continues to teach us new tricks.

Xrefs, Meet Your New Manager

An hour or so before our regular team meeting, our manager-to-be came to see me at my desk. She’d spent three hours researching cross references versus hyperlinks in our Flare projects, and she was stopping by to let me know that she disagreed with my assessment that we should use both. She didn’t want her opinion to be a surprise to me in the meeting when it came time to vote on our latest debate:  whether to switch all of our hyperlinks to cross-references. I’d spent some time putting together a handout for the other folks on our team to compare our options, and I’d also made a case for using both so that we could still use links that didn’t refer to topic headings.

 

Manager-to-be sat down and explained to me why she though we should replace all of the hyperlinks, and we discussed some examples of how content could be reworked to accommodate the change. After our conversation, I’m confident that the specific how-tos of applying this change to our thousands of legacy topics will be covered for our less enthusiastic Flare-adopters, because I can tell that she considered that.

 

 

I do not want to be the person whose feelings have to be tip-toed around and massaged, nor am I in a position at our company where it is my job to monitor team morale. I keep that weather-vane up for pragmatic purposes, not altruistic ones. Is this solution I’m proposing good for everybody or just good for me? If it’s just good for me, it can’t be a department standard, and I want my projects to follow the standards. I want to know if I’m wasting my time, too—is someone already working on a solution that seems more promising? As our tasks get increasingly technical with the advent of Flare, good communication on our team can keep us from duplicating efforts or traveling too far down the wrong roads. Plus, let’s just say the farmer in me wants to know which way the wind is blowing. If it’s looking like sunny skies, I am perfectly happy to keep my eye on the row I’m hoeing. And I won’t need my back scratched while I’m doing it.

 

 

That said, what is up with the cross-references, already? Some of you may have seen my ongoing Twitter posts about whether to go 100% xref and wondered what the fuss is about. Our department is even going to vote on it, for Pete’s sake. But this decision embodies all of the elements that have tripped us up during our implementation of Flare: variations in formatting across projects, team members being at varying stages of development across projects, inexperience with help-authoring, and difficulty setting standards when our technical knowledge is still growing. The voting thing is management’s attempt to get a grip on the amoebic nature of our Flare standards.

 

 

Then we learned this week that in addition to our team lead, we will now have a Tech Comm manager; one with experience with the issues we’re encountering. She’ll have the authority and the know-how to take those issues to the management table, if need be, and speak about them like a tech writer. From what I’ve seen, she’s also professional, open, and respectful. The skies are indeed looking sunny.