Top 4 tactics to structure legacy documentation

The success of a move to topic-based authoring and/or structured writing depends on the order of your steps – and good planning is key. You can’t make it up as you go along.

The Company I Work For is moving its extensive user documentation to topic-based authoring and a DITA-compliant information model. That requires converting existing documentation, such as user manuals.

Many current manuals are like tutorials: They guide readers by example with lots of screenshots. They are easy to follow along, but more difficult when you need to know about individual procedures or about scenarios which don’t match the example.

I’m currently converting and restructuring some of these user manuals into topics. Basically, I’m taking them apart and reconstructing them into concept topics, procedure topics and reference information.

Here are some lessons we learned in the process:

1. Define the structure first.

Even if it takes a week or two, be sure you have 80, 90% of your structure in place before you start tearing up contents to convert them. If you simply make it up as you go along, you’ll get an abstraction of whatever content you start with – which most likely won’t suit all of your contents.

You’ll be better off, if you at least sketch out the common topic types such as concepts, procedures and reference and define what goes into them in which order.

For example, procedure topics could contain

  1. One or two intro/context paragraphs
  2. Prerequisites (if any)
  3. Procedure as a list of numbered steps
  4. Expected results
  5. Exception handling (if possible and applicable)

2. Carefully select pilot projects.

Start by converting content that is both typical and mainstream. This way, you can validate your structure and discover gaps or errors.

This also makes it easier to show progress and reap some quick wins. You can give managers and colleagues something tangible what the future documentation will look like to ensure confidence and support on your path.

3. Draft the new topic structure.

Use the defined structure to draft a specific structure for the content you’re about to convert. Just leafing through the pages of a manual will give you a pretty good idea which topics you will be able to create from it.

Order all those topics into a structure, so you have sort of a table of contents for the new topic-based manual before you begin. This structure need not be set in stone, if you find you need to arrange or add topics, but it should present a sensible picture.

Ensure, for example, that procedural topics are backed up sufficiently by concept topics so we have room to explain the “what” before you explain the “how-to”. Or, if you have both setup procedures and operational procedures, ensure that setup corresponds to operations.

4. Proceed along the old content.

In the actual conversion process of chunking text, moving it into the new structure and rewriting it, follow along the old structure. That will create a temporary mess in your new structure where you may find yourself dumping random paragraphs and sentences under headings.

But this allows you to cross off section by section in the old manual with the confidence that you have moved it over. This is much faster and more reliable than constantly going back to the old manual, worrying if you’ve left anything behind.

Your turn

Do you find these tactics helpful? What experiences have you had when converting legacy content into structured documentation? Feel free to leave a comment.