Writing good documentation

What makes good documentation?  Should it be very detailed, or just a "quick guide"?  Should it be paper or online?  Which works better?

I've done a lot of documentation, in almost every possible format.  Here's what I think about it.

• The writing should be clear and concise.  The fewer words, the better.  I tend to write the first draft quickly, then go back and revise, taking out words and simplifying sentences. I'm doing it as I write this.

• Technical documentation needs both words and pictures. (See Learning styles for more on this.)

• There's a tendency in law firms to over-formalize documentation.  If the client wants it, I'll do it, of course.  But I don't recommend it.  Using the active voice, the occasional contraction ("don't" instead of "do not"), and "you" (not "the user") is simply more effective documentation.  You don't have to be cute or over-friendly, but language that sounds like natural speech is easier to relate to and remember.  And that's what documentation should be all about.

• Proofread.  Proofread.  Proofread.  And before you do - in fact, before you write the documentation - read a little book called, The Elements of Style.  It's been revised a number of times, and it's worth its weight in gold to anybody who writes anything.  (Page 1 explains the difference between "its" and "it's" - a difference that too many people don't understand. See previous sentence.)

• While we're on the subject of books, I also recommend this one.
  Un-technical Writing.  One comment from it I remember well. Sometimes a one-word manual is needed - the word "Push" - for doors that are designed with a "pull" handle on the "push" side of the door!

• Agree on a style manual, and use it.  (I once worked for someone who wanted a style manual, agreed on the one we should use, then, the first time the style manual disagreed with her, told me to "go out and buy a style manual that does agree with us." She meant her, of course, not "us."  I lasted all of six months in that job - the worst six months of my working life - but I still stayed longer than most of my successors did.)

• Don't use all caps for titles - at least, titles that consist of more than one word.  The tradition of using all capitals and initial capitals stems from typewriters with only one font style and size - it was a way to differentiate headings.  It's no longer necessary, and we find capitals harder to read than lower-case letters.

• Include screen captures whenever possible.  While lawyers are used to reading words, almost everyone learns quicker from pictures.