"Making the Most of Service Manuals"

[Chris Borokowski]

This is why I've always felt that the "getting started" or "about"
chapter of the documentation is the most important. In it, you describe
the basic theory and terminology of the tasks and procedures ahead. If
the end user is mentally alert, this provides most of what they are
going to need.

For the divergence in user groups, with some being experts and others
being new, there are a number of strategies you can use when planning
the documentation. One is to publish a "pocket guide" that's a
telegraphic summary of common procedures, and variations. Another is to
offer a "cookbook" to show common use cases to new users. One that I
favor is to give new users a powerful introduction in the first
chapter, and then offer "summaries" on each subsequent chapter which
contain the short version of events the experts will want.

One difficulty is addressing new users without appearing to assume
they're stupid. I write for the inexperienced but try not to write "for
dummies" manuals. I can put instructions in a direct and simple form,
but trying to ignore the distinction between "inexperienced" and
"clueless" creates a manual that will bore everyone.

--- techwr-l-request at lists.techwr-l.com wrote:

> That's all well and good if you know your audience is composed
> exclusively of who already know the equipment and only need the
> documentation to refresh their memory. However, if your audience
> includes new users, you're doing them a disservice by catering to the
> experienced users and omitting detail. In addition, leaving the
> detail out of the documentation imposes a training requirement on the
> experienced users. In most cases, it's the job of the documentation
> to relieve experienced users of that burden.

http://technical-writing.dionysius.com/
technical writing | consulting | development

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com