RE: Document Conventions

Subject: RE: Document Conventions
From: "Higgins, Lisa" <LHiggins -at- carrieraccess -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 19 Sep 2000 13:05:16 -0600

> -icon use (mainly for completeness, but it is nice to
> distinguish what a warning means instead of a caution, as well as
> defining what platform-specific icons indicate)

I always include a warnings, cautions, and dangers section when it's
applicable. However, when I use them, I state explicitly what they mean.

> -flavor of Backus-Naur Format (BNF) use

This is necessary, sure, for your applications, but I would argue that this
information should be integrated into the document beyond a 'conventions'

> One Techwr-l respondent states that she doesn't include a conventions
> section because no one reads it.

No, I didn't. I said that I don't include it because it's unnecessary, which
is, not coincidentally, also the reason that people don't read it.

Not necessary (cause) --> I don't include it (effect)
Not necessary (cause) --> People don't read it (effect)

> If we always took that extreme position, we wouldn't write
> documentation, because no one reads it :)

I know we say that a lot, and I know it's often true. But most users will
check documentation when they need information or when they're stuck. Most
manuals are probably a last resort. That's why they have to be easy to
use--because really angry, frustrated people are trying to find information
in them. And I have seen documents that were rendered unusable by
meta-information, convoluted information paths, and other little tech writer
thingies that tend to do more harm than good.

Will it hurt anything to include a half page of explanation of the
conventions you've used in a document? Well, no. Not as long as you don't
forget to explain your conventions where they're used. And not as long as
you don't let your 'Document Conventions' serve as a substitute for good
design. And as long as you don't let it get out of hand.

A half-page section won't hurt. Probably won't help, but it won't hurt,
either, until you use that reasoning for six or seven other little pieces of
extraneous information. I've mentioned this before, but I am familiar with
manuals that, because of their unweildy infrastructure and 'How to use this
manual' information, do more harm than good. When these manuals were
introduced in the product lines, tech support calls went UP. The information
the users needed in order to follow the instructions was so daunting and
time-consuming that the manuals did little more than intimidate them. And
these manuals WERE intimidating. Big honking monstrous things with headers
THREE LINES LONG, full of the most arcane and trivial detail you could
imagine, with, of course, a corresponding section in the 'About this Manual'
section explaining how to decode the volumes of ridiculously prissy little
detail about the administrative details of writing the manual.*

This is an extreme example, yes, but it's all about metadata.

I'm not endorsing taking out copyright and trademark information, or not
explaining warnings, cautions, and dangers. All I'm saying is there is no
good, valid reason to include a section at the front of your book saying
that Courier font indicates system text, bold Courier indicates something
you should type, blah blah blah.

If the information needs explaining, it needs explaining as it occurs, not
in a separate section.

* This was at another job. If it had been here, I'd have posted anonymously.

This email may contain confidential and privileged
material for the sole use of the intended recipient. Any
unauthorized review, use or distribution by others is
strictly prohibited. If you are not the intended recipient
please contact the sender and delete all copies.

Previous by Author: RE: Document Conventions
Next by Author: RE: Salary Review...
Previous by Thread: RE: Document Conventions
Next by Thread: Re: Document Conventions

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

Sponsored Ads

Sponsored Ads