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…

Advertisements

3 Responses

  1. Well put. This is a major problem when converting legacy content to DITA. Unstructured content like this requires considerable upfront work to rearchitect as it goes into DITA.

  2. […] go a long way, but they shouldn’t replace entire concept topics. Also see my previous post When topics don’t quite work from two years […]

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: