User documentation: setting goals

The Goals

As noted elsewhere and often in Words and Technology, any dialogue worth its salt has some very simple goals:

  1. to persuade the reader/user to adopt an attitude and/or belief and act on it
  2. to educate
  3. to entertain
  4. to simplify a task
  5. to expedite completion of a task

As with any dialogue, great user documentation achieves all of these goals. Entertainment is the most difficult of these goals to achieve, but it’s not out of reach. The best user documentation makes it fun to learn. The essential goals, however, are to communicate how to use your product and to expedite usage. If you reach these two goals, you and your team have done your job.

Getting your ducks in a row

There’s no secret formula for creating great user documentation. You line up your ducks and go at it.

But have you ever tried to get ducks in a row? The damn things keep wandering off.

In my experience, writing user documentation is pretty much like writing anything. It’s a process of discovery involving numerous feedback loops. You can draw it up as a straight-line process, but expect a few turns in the road and to revisit steps you thought you’d completed. Using, rather than ignoring the feedback loop, will produce better user documentation in the end. With these caveats in mind, let’s take a look at the do’s and don’ts of each stage in the process.

Plan >  Write >  Revise >  Edit

Posted in Technical Documentation

Leave a Reply

Your email address will not be published. Required fields are marked *


* Copy This Password *

* Type Or Paste Password Here *

%d bloggers like this: