Four rules for good documentation

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:

  1. Poor grammar and bad writing are often a sign of poor comprehension.
  2. Good documentation takes time.
  3. Deep expertise is not automatically a prerequisite for good documentation.
  4. 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.

Helping users become experts

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?

Continue reading

Resources for information design

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.

Weekly links roundup

  • A great article (it’s a PDF) by Anne Gentle, Lisa Dyer, and Michael Priestly on building a DITA-wiki hybrid.
  • Does working on screen change the way we think? This blog post speculates that it just might.
  • Mike Hughes discusses two ways in which user assistance adds value, and how to communicate that value to the suits.
  • Need to build a DITA specialization? Then check out this online tool.
  • The stem sentence debate: a cause for concern, or just a quibble? Read this article and then decide.

Talking about podcasting

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.