Don’t Be Strangled by Strict Documentation Organization

Friday, September 18th, 2009 | Technical Communication, Writing Theory & Practice

While doing some work documenting an internal face on a third-party application for a specific set of users, I came across what seemed a superfluous help topic for that application. It looked something like this (going from memory here):

Deleting an Instance

You can delete an instance if needed.

To delete an instance

In the search, where I came across this topic, right next to each other were listed “Deleting an instance” and “To delete an instance.” If you were looking for the instructions for deleting an instance, which one would you pick? If you thought about the nuances of the phrasing, you might pick the second. But when you have a task to get done, you’re not thinking about nuances of language. You click the most likely candidate.

My guess is that the help author had a structure for categorizing topics, and the instructions for deleting an instance ended up alone in a category. That’s just a guess. But it made me think that if I’m right, then the organization of the help was too strict.

When planning a set of documentation, don’t make the organization so strict that you can’t leave out superfluous topics like this. Allow yourself the flexibility to cut to the chase when it’s appropriate.

Share This