Re: Style Guides and Documentation Standards

Subject: Re: Style Guides and Documentation Standards
From: "Miller, Lisa" <Lisa -dot- Miller -at- ANHEUSER-BUSCH -dot- COM>
Date: Thu, 3 Jun 1999 10:46:54 -0500


We're working on a style and standards guide here as well. The issues you seem
to be covering are similar to what we currently have. As I was reviewing the
documents yesterday, it occurred to me that most writers will make this
decisions on their own. I have seldom referred to a style/standard guides to
answer the questions you pose. If there is a standard, then there usually is a
template. I follow the template. However, I did come up with questions that I
am often faced with that very few companies address. These are:

Company-specific abbreviations
Standard Deliverables
Deliverable (expected) content
Use of third/second/first person
Level of detail
Resource material
Directory structures
Information currently known about the audience
Standard Review process
Roles and Responsibilities

I'm going to recommend that some of this information be added to our standards
guide. I'm sure that not all of these topics apply to all industries, but some
do or at least should.

Lisa Miller
Technical Writer

-----Original Message-----
From: Tom Johnson [SMTP:johnsont -at- STARCUTTER -dot- COM]
Sent: Thursday, June 03, 1999 10:36 AM
Subject: Style Guides and Documentation Standards

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
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.
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
glean what we could and collate them all into one set of "best
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
expensive if you have to start buying more than one or two specific

Is there a cross-over between style guides and documentation standards?
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
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=

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

Previous by Author: Re: When do you start addressing new SW versions?
Next by Author: Re: Style Guides and Documentation Standards
Previous by Thread: Style Guides and Documentation Standards
Next by Thread: Re: Style Guides and Documentation Standards

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

Sponsored Ads