What makes good documentation? Should it be very detailed, or just a
"quick guide"? Should it be paper or online? Which works
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. 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
Include screen captures
whenever possible. While lawyers are used to reading words, almost
everyone learns quicker from pictures.
What about online documentation or
"Help" files? Do they work?
Yes, if they're well written and
designed - and if the user knows about them. It's tricky to come up with
the right mix of clear, simple writing, with links to more detail, because
people can be frustrated if they have to click on successive links to find a
Good online documentation can also
be converted easily to quick reference guides, and vice versa.
Many people have a resistance to
using online documentation, though, with memories of poorly written and designed
Help files fixed firmly in their brains. So it needs to be marketed, not
just dropped there under the "Help" menu, or your (or my) time and effort will