Found this excellent article today from a link on my Twitter feed. The first consideration in technical communication is, first and foremost, our audience (or stakeholders, as the article defines them). And based on this writer’s experience, some folks (more specifically, those who actually take an interest in what you’re writing about) still like to print off the pages they need and read them at their leisure. The audience is more interested in a story than just what’s presented in topic-based documentation (when they bother to read, that is).

I’m inclined to agree.

When I learned how to develop online help systems back in 1992 (in Deerfield, Illinois, specifically, at a week-long class conduced by a little company called Communitech), that was where I first heard about developing topic-based documentation, but only in the context of creating online help. I remember the one thing that was repeated to us several times a day: users access online help when they need specific information on a single task they are trying to complete as they work.  No more, no less.  And that’s where topic-based documentation works best. 

But the topic-based approach might not work well in all documentation instances, no matter how hard we try to steer our customers, stakeholders, or audience in that direction.  An article I read last week puzzles over that very issue. 

Then there’s the ease of updating that is a big selling point for topic-based documentation.  From the writer’s perspective, it makes the job easier.  But are we in this for ourselves or for our audience?  Updating a set of user materials (printed guide, online help, any external media, etc.) with text and screen shots or drawings can be tedious, and something just short of an archeological expedition if you’re updating old documents that you didn’t write.  For me, that’s always been part of the job, the challenge to make sure the audience has everything it needs to understand what you’re writing about. 

In my experience, audiences want context.  They want to see how the peel relates to the banana, so to speak.  You don’t have to say a lot, but making that contextual connection can provide better understanding.

Advertisements