Re: Re: "Making the Most of Service Manuals"

Subject: Re: Re: "Making the Most of Service Manuals"
From: Chris Borokowski <athloi -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 11 Apr 2008 07:35:42 -0700 (PDT)

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 -dot- techwr-l -dot- 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.
technical writing | consulting | development

Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: Replacing "master" and "slave" terminology
Next by Author: Writing as inspiring users
Previous by Thread: Re: "Making the Most of Service Manuals"
Next by Thread: RE: "Making the Most of Service Manuals"

What this post helpful? Share it with friends and colleagues:

Sponsored Ads