Re: Style Guides and Documentation Standards

["Miller, Lisa" <Lisa -dot- Miller -at- ANHEUSER-BUSCH -dot- COM>]

Tom:

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
        To:     TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
        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)
        questions.

        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?

        <<Snip>>

        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
        standards.

        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=




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