Style Guides and Documentation Standards

Subject: Style Guides and Documentation Standards
From: Tom Johnson <johnsont -at- STARCUTTER -dot- COM>
Date: Thu, 3 Jun 1999 11:36:28 -0400

In an earlier post I offered a few suggestions for things that might be
covered in a style guide for technical writers. My examples were not the
best ones, only things I've wondered about from time to time. I received
one reply that offered the following answers to my (hypothetical)

Tom Johnson asked:
1. Should captions be above or below a picture?
2. Should illustrations have a border around them?
3. Where should trademark information be listed?
4. What symbols should be used to identify warnings or cautions?
5. What is the difference between a Warning and a Caution? Danger?


As for the questions above:

1&2 are design issues that would provide little benefit if forced on every
one. For each customer/client choose what they think is best and be
consistent within the set of documentation produced.

3 seems to be universally accepted already in all forms of publishing.

4 should be answered by which ever standards organisation your group
believes to be the authority or which one is the authority for your
audience. ANSI, ISO, CSA, IEEE, BSA, etcetra.

5 For our purposes we use notes, cautions and warnings throughout our
manuals. Notes serve as a guide to aid work or maintenance tasks. Cautions
warn of possible equipment damage. Warnings serve to warn of possible
personnel injury or death. These definitions are spelt out in the
frontmatter of all our manuals.

Now my question is this:
ANSI, ISO and other standards organizations have small sections of their
standards aimed at documentation. Would it make sense to bring these
"standards" under one label and call it a style guide? Some of them are
very specific towards particular industries, but would it make any sense to
glean what we could and collate them all into one set of "best practices?"
My thought is that one reference book could be really handy. I've been
through the process of trying to find out what standard even talks about
documentation. It can be a royal pain to find what you are looking for and
expensive if you have to start buying more than one or two specific

Is there a cross-over between style guides and documentation standards? I
would like to find out what the standards are. Are you writing to any
particular standards? If so, please send a message to me and I'll compile
them for the list.

Please include information about which industry or subject the standard
applies to and any contact information for the governing body.

Tom Johnson
Elk Rapids, Michigan - On the freshwater coast

johnsont -at- starcutter -dot- com work
thomasj -at- freeway -dot- net personal

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Punctuation tips (not that you need them!)
Next by Author: Re: sentence case
Previous by Thread: Providing References (Was: Interview from hell - recommendations)
Next by Thread: Re: Style Guides and Documentation Standards

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

Sponsored Ads