When topics don’t quite work

If a topic in your documentation gives you trouble, seems homeless or doesn’t quite “work”, it’s probably because it is mixing topic types.

The company I work for has started to roll out topic-based authoring over a year ago. We’ve seen several benefits already: Topics are easier to find and follow for users and more efficient to maintain for writers. But the transition has not been without problems…

The curse of the ornery topic

One of the biggest headaches for us is the “ornery topic”. Here’s how you can tell an ornery topic:

• It seems homeless. Regardless where you put it, it seems out of place somehow.
• It doesn’t quite work. It doesn’t really do what the heading says, but somehow does more or less or differently.
• It seems essential. You really need the information. You can’t just cut it out.

The #1 cause for ornery topics is mixing topic types. What often happens is this:

1. We need to explain how to do something, so we write a procedure.
2. Then we need to provide some context about the task, so we include some concept information.
3. Then we need to tell the customer about all the available settings and options, so we include some reference information.

Voilà, our topic’s become ornery! – If you’re into project management, think of this as the molecular tech comm version of scope creep.

The cure for the ornery topic

We’ve by now found several ways you can bring an ornery topic back in line:

• Extract concept information, put it into a concept topic and link to it.
• Omit reference information in the topic, if it is sufficiently explained elsewhere, for example in online help entries.
• Make the procedure rule the topic structure, so you have intro/context, prerequisites, procedural steps, result.
• Limit context information to what fits into an introductory paragraph (and link to other concept topics)
• Limit reference information to what fits into individual steps (and link to other related reference topics)

Your turn

Have you met any ornery topics in your documentation? How have you addressed them? Feel free to leave a comment…

Advertisement