Home Feedback Contents Search


Technology Training, E-Learning and Documentation for New York Law Firms

[Under Construction]

My Resume
Why hire me?
Client Testimonials
Work samples
Comparing authors
Learning styles
30 Tips

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. 

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 simple answer.

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 be wasted.


Last modified: 04/28/08