Re: Document Conventions

Subject: Re: Document Conventions
From: "Christensen, Kent" <lkchris -at- sandia -dot- gov>
To: "'TECHWR-L'" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Wed, 20 Sep 2000 09:05:37 -0600

It depends on the type of manual, doesn't it?

If your manual is one of a series covering aircraft maintenance, perhaps
there is an entire manual describing the conventions used in the whole
series. What's the difference between "warning" and "caution," for example.
Maybe technicians study the conventions manual and pass a test before
they're allowed to work from the actual maintenance manuals. I think use of
fonts to imply meaning is unlikely in such scenarios, by the way.

If, instead, your manual is for consumer genealogy software or something,
the approach that the reader is under some compliance requirement to perform
according to the writer's direction--which I think use of conventions could
imply--is likely not a good way to go.

Bruce Byfield says it well: "I always try to keep this section as short as
possible. That means I also try to use as few design and wording conventions
as possible. Maybe I'm just a lazy reader, but, if I'm any example, I find
too many conventions hard to remember. Deciphering an entire legion of
conventions is worse than squinting at the symbols in a Michelin guide."

I guess in a consumer product I wouldn't mind a few conventions as long as
I'm not required to know and understand them to successfully use the manual.
If they were explained way in the back that would be ok, as long as the only
reference to this section was in the table of contents. If nothing else,
occasional use of color or different fonts makes the manual look less
intimidating, but, at the same time, it could direct the eye to more
important information without need to say so. I think the writer should
work his/her magic while remaining in the background in these instances.

Previous by Author: re: Linking to graphics: why, why not?
Next by Author: re: Technical writing and Marketing
Previous by Thread: Re: Document Conventions
Next by Thread: Linking to graphics: why, why not?

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

Sponsored Ads

Sponsored Ads