What an autistic child taught me about technical writing

My daughter Thais is autistic. A few months ago on my freelance writing blog, I wrote about how Thais taught me a few lessons that I was able to apply to my freelance writing.

Recently, I began thinking about how dealing with my daughter’s condition has influenced my technical writing. It has, in a few significant ways.

Continue reading

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.