Re: Writing procedures

Subject: Re: Writing procedures
From: Peter Neilson <neilson -at- windstream -dot- net>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 16 Jul 2009 07:21:10 -0400

Those questions are all upside down, and are the source of what users
see as documentation that is difficult to use. You are ahead of
yourself, and need to back up and get a proper documentation plan. Start
instead with this question:

- For whom are you writing?

1. If you are writing for the beginning user, you should document only
the aspects he needs to get started properly.

2. If you are writing for advanced users, or for those driven by
curiousity, you might be creating a reference manual, and should
document many of the more complicated aspects. In general, a reference
manual should document everything. But see #3, below.

3. If you are writing for your own manager, and he's an insane
nit-picker who demands every aspect be thoroughly documented, only then
should you describe the totally obvious in detail. "Clicking the mouse
(see "Using the Mouse" in section on the "Click here to quit"
button quits the application."

Reader #3 rarely reads the documentation, but merely notices its size
and its presence. That kind of documentation is rightly called
"shelfware". If the boss says it is too small, you could fluff it out
with a section of the Copenhagen telephone directory--perhaps the
listings for Jensen or for Larsen--and no one would notice.

I've not addressed the issue of "internals" documentation, in which you
interview the designers and developers to find out how they came up with
the requirements and the design. It's my impression that most outfits
rely solely on the developers' notes and the source-code comments
instead of creating official internals docs.

Raj wrote:
> The following are a few basic questions.
> Should all the fields in a screen be described in a procedure. Or, should only the fields that the user types an entry should be documented?
> Also, if the user searches for information, should all the information on that screen be documented, or only those headings that are not self explanatory be described?
> Can background processes be described in the procedure itself or as notes?


Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

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.

Please move off-topic discussions to the Chat list, at:

Writing procedures: From: Raj

Previous by Author: Re: job-hunt weirdness
Next by Author: Re: job-hunt weirdness
Previous by Thread: RE: Writing procedures
Next by Thread: Writing procedures?

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

Sponsored Ads