How many times have you read bad documentation? Far too often, I’m sure. You can’t just dismiss it by saying “Oh, that was written by a developer.” It wasn’t; not always, anyway. I’ve read and taken over bad manuals that were written by professional technical writers.
But you can avoid bad documentation. How? By following the following four rules from an article in Red Hat Magazine:
- Poor grammar and bad writing are often a sign of poor comprehension.
- Good documentation takes time.
- Deep expertise is not automatically a prerequisite for good documentation.
- Don’t let working cultures that put too great a premium on knowing everything dominate
Of course, the article goes into each rule in detail. One sentence, though, sums the entire article up:
Good docs come from good writers.
In this blog post, Gordon McLean discusses the need to move users from the state of being super novices to being experts. While Gordon starts his discussion with a presentation he attended given by a usability professional, he ponders how to apply the insights that he gleaned from the presentation to technical communications:
It’s fairly easy to get into the mindset of the beginner; presume the reader knows nothing and assume a level of learning in which to frame the information. Expert level information is a little trickier but could be stated as specialist, or niche, information.
But what of the super-novice? If we want people to get the most from our applications (and we do, don’t we?) how do we enable the super-novices and help them become experts?
One of the cornerstones of good documentation is solid information design. If you’re interested in increasing your knowledge of the subject, then check out this set of documents and links. They’re part of an information design course established by Thom Haller. If you’ve been in the tech comm game for a while, some of the information might seem old hat. But it’s a good refresher, and a good starting point for anyone new to information design.
In a recent blog post, Fabrice Talbot made the following interesting observation:
… the documentation industry is promoting single-sourcing as THE SOLUTION to all their problems. However, for smaller companies the costs of moving to single-source (or XML, or both) may outreach the benefits. I could not agree more …
In case you didn’t listen to last week’s podcast, Aaron and I will be giving a presentation at the May 13 meeting of the Toronto chapter of the STC. The title of the presentation is “The Ears Have It”, and it will discuss how podcasts:
- Can help maintain an ongoing dialogue about a particular domain or topic
- Are a great way to disseminate new developments
- Are available anytime, anywhere, at the user’s convenience
- Make supplementary material more interesting
We’ll also be outlining the mechanics of podcasting, analyzing why some popular training and educational podcasts are successful, and how you can use the same techniques with your audio materials.
If you’re in the Toronto area, why not drop in, have a listen, and ask a few questions? You can get directions to the meeting here.