Top 4 steps from manuals to topics

A little bit of planning ensures you get clean, manageable topics from your conversion of user manuals.

While most help authoring tools support importing Word documents, there’s more to getting re-usable topics out of user manuals, as I’ve found out. I’ve spent the last few weeks converting 3 related Word manuals of 360 pages into 400 topics in Madcap Flare – though I believe that the process below applies to other tools as well.

The aim was to merge the contents from separate Word-to-PDF manuals with the online help topics into a single sourcing repository from which we can create both online help and manuals.

My two key lessons of the conversion are:

  • Plan first, execute second – several hundred topics are too many for trial & error and picking up the pieces later.
  • Do each task as early as possible – some Word idiosyncrasies are hard to clean up after the conversion.

And here’s how I did it in 4 steps:

 

1. Start with plans

The whole conversion exercise benefitted much from a couple of designs that I followed:

  • An information model
  • A folder structure for my topics

The information model defines the 4 topic types we have and what each type contains internally. It’s basically “DITA, without the boring parts” about which I blogged previously.

The folder structure divides my one Flare project into several sub-folders, so I don’t have 400 topics in one heap. Instead, I now have 13 sub-folders which divide up my topics by topic type (concept, task or reference) and even by task type (initial setup or daily workflow). That makes it easier to manage the topic files.

2. Prepare for the import

Once I had the basic structure to organize topics and their insides, I prepared my Word manuals, so I didn’t have to deal with a GIGO situation, where I get Garbage In, Garbage Out.

First, I edited the documents into topics, so each section could become either a concept, task or reference topic – or an auxiliary topic which ensures that the chunks still flow nicely when you read them in the future manual output. I also ensured that section headings indicate topic contents and type:

  • Concept topics use noun phrases as headings
  • Task topics start with an imperative

Then, I cleaned up the documents. You can convert unstructured Word with layout applied in styles, modified styles and manual formatting into topics just fine, but it will give you unmanageable content and endless grief. So do your future self a favor and dissolve all modified styles and manual formatting.

3. Import

Thus prepared, I’ve found that Flare’s built-in Word import is very good, consistent and reliable if you throw well-structured Word documents at it. Only tables didn’t import well (or I couldn’t figure out how to do it), so I re-styled them in Flare.

If you’re a stickler for clean topics, you can go ahead in Flare and clean out unnecessary remnants:

  • Remove Word’s reference tags in cross references by replacing *.htm#_Ref1234567″ with *.htm”
  • Remove Word’s Toc tags in Flare’s table of contents by replacing *.htm#_Toc1234567″ with *.htm”
  • Remove Word’s Toc anchors in topics by deleting <a name=”_Toc*”></a>

4. Adding value to topics

At this point, I had a pile of 400 clean topics, but no added value from the conversion yet. That came from additional tasks:

  • Dividing up topic files into the folder structure, which makes hundreds of topic files manageable.
  • Assigning a topic type to topic files (Flare lets you do that for several files at once, so this was very fast), which makes the content intelligent, because topics “know” what they are.
  • Assigning in-topic elements (as div tags) to topic paragraphs according to the information model, which allows you to identify and reuse even parts of topics, for example, instruction sections or example sections.
  • Creating relationship tables for cross-references into relationship tables where feasible, which ensures that links are easier to manage and to keep up to date.

Your turn

Have you done a similar conversion? What were your experiences? Did you do it yourself or with an outside consultant? Feel free to leave a comment.

Advertisements

13 Responses

  1. That’s a good list, Kai. But I’ve always been in awe of people who during the planning stage can think of every nuance of file naming, reuse, and so forth that will come into play during the conversion.

    For me the sequence usually goes something like this:
    – Plan
    – Prepare
    – Plan again
    – Prepare some more
    – Import a small percentage of the content
    – Plan again
    – Prepare again
    – Import the rest
    – Add value

    All done, finally. Whew!

    • Thanks, Larry, for your thoughts – I must admit you sorta caught me here: My first idea for a file structure was 3 directories, 1 per source manual. I gave that up when I imported the first manual and found I had more than 100 topics that I couldn’t manage very well. So I’ve actually followed your process – but just blogged the result… 🙂

  2. I’ve done something similar, importing Word docs into Author-it. Cleaning up the Word docs was an absolutely vital step. I applied a standard template (the most generic one that I publish to) and used the Word Style dialog to reduce all modified styles to what I needed. (CTRL-Q doesn’t work if everything starts from Header + Arial 14pt Bold Underline…) Maximising the single-sourcing value by finding candidates for re-use, and then consolidating them to a single instance… well, that was hard to automate. Still haven’t found a nice answer, it relies on familiarity with the literature and a very good memory for what you’ve encountered before.

    • Thanks, Sarah, for your comment. Yes, I would imagine the process would also work for Author-it. I agree that it’s virtually impossible to automate the consolidation for reusing contents. So it was good that we budgeted a little time to go over topics again and tweak them and their structure to ensure they work nicely in print (as before) and online (in the new deliverables).

  3. Good post, Kai. Topic-oriented architecture not only helps in classifying information types (concept, task, reference), but also helps in getting rid of most of the nice to have information in the user manuals. Minimalism coupled with topic-based authoring can go a long way in increasing the usability of the user documentation. Tools like IBM Information Architecture Workbench can come handy for creating the topic outline.

    • Thanks, Alok. I agree: Minimalism is the perfect complement and makes the migration a good opportunity to weed out content that’s unnecessary or even redundant. Thanks also for the pointer to IBM’s workbench. I’m not familiar with that tool (I don’t even use mindmaps, but instead simply run a text file to draft topic structures…) But I’ll be sure to check it out!

  4. I’m in the act of evaluating Flare at present, with the aim of converting our Word documents to Flare, so many of your recent posts have been extremely useful to me, and contain nuggets of pure gold. Thank you!

    This post triggers a question. Some of my documents have lots of repeated content, which I was expecting to manage using snippets, possibly containing some conditionally tagged text. But I’m interested to hear what you mean by using div tags “to identify and reuse even parts of topics”, as this sounds very useful too. How do you go about reusing content in div tags in Flare? I wasn’t aware that Flare supported anything like that.

    • Thanks, titch990, for your comment. Yes, I guess you would be using snippets to reuse content like yours – at least we do… 🙂 In fact, I have some of my “div-tagged” reusable content in Flare snippets.

      The reuse by div tags I mentioned means to reuse (potentially and in the future) content by crawling over all Flare topics and extracting all the examples (which could be useful for training materials) or all user scenarios (which could be useful for marketing). We hope for this benefit as a windfall from XML topics. However, as far as I know, Flare as a tool won’t help with that – it merely gets out of the way and lets us do that, if we want to, using external text or CMS tools.

  5. I am in the middle of transitioning to Flare, and I am struggling with how to define a topic. “Enough to stand on it’s own” lacks some context I apparently need and I seem to just be recreating my old HTML files. The info doesn’t appear to sort neatly into concept, task, reference categories. Any tips after your project to share with a TBA newbie?

    • Hi, Michelle. Yes, getting the hang of topics can be tricky in the beginning. I would first try to figure out whether the topic types concept, task, reference are right for you. For example, when you write software documentation, they probably are. When you write a cookbook, you probably want an (additional) topic type “recipe” – obviously.

      In terms of learning to distinguish topic types and sorting contents into topics, I found it easiest to start by teasing out reference information from my content. Reference information is commonly stuff like field help: What can be entered or shown in a field, what are permitted values, what is the default setting, stuff like that.

      Separating concept info from task info can take a while to get used to. It helped me to have a clearly defined structure for task topics which contain these sections:
      1) Introduction, optional
      2) Prerequisites of task, if applicable
      3) Instructional steps for task, mandatory
      4) Results, if not obvious
      5) Next steps, if not obvious
      6) Error handling, if applicable

      Anything that doesn’t fit into this structure, especially, when it’s abstract, explanatory and not directly related to any of the sections above is probably concept material. (Personally, I consider it valid to include a sentence or two of concept in the introduction section to create the context in which a task should be performed, but I understand opinions about this differ.)

      P.S. You probably know already that Flare does not necessarily require you to write clear, clean topics using the three types, so I’m assuming you have some further motivation to use topic-based authoring…

      Hope this helps. 🙂

      • Thanks, Kai! I also found this PPT (http://tc.eserver.org/35431.html) which along with your response has helped a bunch. It’s nice to finally be flush with context.

      • Glad I could help, Michelle! Thank you in return for linking to Larry Kunz’s “Concept, Task, Reference: A Practical Guide to Choosing the Right Topic Type” presentation which does a very good job of summarizing the distinctions of topics and their best practices!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: