5 steps from legacy documentation to topics

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc.

Prerequisites

• Some knowledge of topic-based authoring. You should know the topic types you will use, for example, concepts, tasks and reference topics.
• Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation.
• A style guide to which your documentation complies definitely helps.

1. Identify topic type(s) per section

Define each section in your manual as one of your topic types, for example, concept, task or reference.

If topic types are mixed…

A common problem at this point is that you may have topics that mix topic types. For example, your topic contains concept information and task information. Or task information and reference information. For details, see When topics don’t quite work.

2. Re-chunk sections to make them topics

Redistribute your content so each section becomes a topic:

1. Cut out everything in a section that doesn’t fit the selected topic type and put it aside.
2. Ensure that the topic that remains:
• Is either a concept or a task or a reference.
• Presents only one idea.
• Has only one purpose.
• Can stand alone, in context with others.
3. Take the content you have cut out and put aside and do one of the following:
• Integrate it into an existing topic where it fits better.
• Create a new topic for it.
• If it’s not relevant, throw it away. 🙂

If topics are too complex…

A common problem at this point is that you can end up with one or several topics that are too complex. Then you can try the following:

• If you can describe a topic’s content as two separate, but related ideas, turn it into two sibling topics.
• If you can fully summarise a topic’s content only as a very complex idea, turn it into a parent topic and create children topics for it.
• If it’s a long procedure with more than 10 main steps in a top-level numbered list, try to cut it into two topics approximately in the middle.

3. Re-sequence your topics

Re-arrange the sequence of your topics, so they flow nicely when users read not just one or two of them, but need to learn a complete setup or operational process.

1. Verify that your topics are in the best possible sequence and re-arrange them if necessary. You might want to try these categories:
• Setup, in the sequence of tasks.
• Operations, in the sequence of tasks.
• Reference topics, in alphabetical order.
• Concept topics can either appear as a section of their own, ordered from the large/general to the small/particular, or among the other topics as appropriate.
2. Verify that your topics are complete and add topics, if necessary:
• Do you have concept topics for all major elements in your task topics which explain what these elements are?
• Do you have task topics for all concept topics which explain how to set up and operate the elements

If the topic sequence doesn’t flow nicely…

A common problem is that the topics don’t flow as nicely once you have chunked them into stand-alone pieces. In this case, add some “glue” topics which orient readers and ensure a good flow, for example, at the beginning of chapters in books. Consider including these glue topics only in print deliverables; maybe they are not necessary in your online help.

4. Rewrite headings to guide readers

Often your legacy section headings work in the context of your manual, but don’t give users enough orientation when they read just one or two topics. Rephrase them so users can quickly dip in and out of your documentation. Keep these guidelines in mind:

• Reflect the user’s need or goal in the heading.
• Phrase headings so users know what’s in the topic when they see only the heading in a link in another topic.
• Try to make headings unique so there’s no confusion when they appear in search result lists.

5. Add links between related topics

Ensure that your topics have links or cross-references between all related topics:

• Do your concept topics link to corresponding task topics – and vice versa?
• Do your task topics include or link to prerequisites and next steps?
• Do your task topics link to corresponding reference topics?

Your turn

Do you find these steps helpful? Have you converted documentation into topics before? Please leave a comment.