Sum: style guide advice (long)

[Hillary Jones <hillary -at- NICHIMEN -dot- COM>]

Delete this if you're not interested in advice on creating an in-house
style guide!

I received so many requests for the messages on creating an in-house
style guide that I'm just going to post them. This is just a long list
of the replies I received, with messages separated by stars.

P.S. My apologies to anyone that didn't intend their advice to become
public domain, but I'm sure everyone will be as grateful for your help
as I am!

**************************************************

Don't recreate the wheel.  Use an established style guide (which one
is up to you) and then just document company-specific styles and
guidelines in your style guide.  Of course, you will need to reference
to the base style guide in your style guide.

My .02 cents.

Steve Myers
Senior Technical Writer
ShowCase Corp.

****************************************************

Here's the outline I just submitted for approval at my company.  Hope
this helps.  Good luck.  Stacey Roberts

I.  Purpose
II.  Scope
III.  Introduction
IV.  Corporate Identity
a. Company Name
b. Company Logo & Color
c.      Company Trademarks
d.      Company Confidentiality Stamps
V.  Document Formatting
a.      fonts (serif fonts versus sans serif fonts)
                b.  styles (style gallery, templates)
c.      margins, column alignment
d.      cover pages
e.      TOCs, indices, appendices,
f.      headers/footers
g.      widows & orphans
VI.  Document Control
                a. Overview of document control
        b. How to send a document through review/validation
c. How to receive sign off / submit for part number
d. How to request documents from document control
VII.    Writing Tips
(Sources:  Chicago Manual of Style, AP Stylebook and Libel Manual,
Microsoft Manual of Style, New York Public Library Desk Reference, The
Random House Basic Manual of Style)
a.      Active vs. Passive Voice
                b. Serial Commas
                yes or no?
                c. Punctuation with Quotes
                d. Possessives
                e. Numbers
                f. Using i.e. versus e.g.
                g. Hyphenation & Modifiers
                back up / backup / back-up
                start up / startup / start-up
                        h. Collective nouns
        data is versus data are
                i. Commonly Confused Words
                ensure / insure
                there / their / they're
                effect / affect
                its / it's

******************************************************

Here's the steps I've gone through to start creating a style guide.

1.  Took stock of the references I had: Chicago, dictionary, industry
style guides
2.  Figure out what types of references we need: "glossary"; conversion
tables, lists of standard "warnings" and "cautions"; document formatting
guides, standardized specifications, etc.
3.  Figured out what I could complete on my own, and what I needed
assistance with (from engineering, graphics, etc). Communicated my
needs.
4.  Compared similar literature, noting similarities and discrepancies.
Took notes.
5.  Took notes whenever I edited...words to add to "glossary" style
guide; common inconsistencies, etc.
6.  Thought about the kind of things I thought important to promote
usability consistency in our literature, and devised ways to apply those
ideas to the literature at hand.

These are all kind of broad, but they may help. To be honest, I'm not
sure how to go about this either, so I've been flying by the seat of my
pants. I tend to write/edit a lot of shorter pieces of literature, so
I'm more concerned with consistency between documents than consistency
within a document (although that is important as well).

Hope this helps!

Jennifer Kraus
jlkraus -at- ametekwater -dot- com

******************************************************

The best reference I can suggest is:
   Read Me First!
  A Style Guide for the Computer Industry
Sun Technical Publications (Prentice Hall)  copyright 1996
ISBN: 0-13-455347-0

It not only identifies what should and should not go into a style guide,
it also includes a CD-ROM with ready-to-use FrameMaker templates.

I heartily recommend it!

 Sue Ellen Adkins                 sea -at- netcom -dot- com

*******************************************************

Here at my job we have been establishing a style guide of our own. What
I would suggest is that you first sit down and look over style guides
that are currently out there - such as the Microsoft Style Guide, Wired,
and so forth. You can also surf the net and find out a lot of
information out there. After you have gathered all that information
together and reviewed it, it is time to figure out where you agree and
disagree with them.

Start compiling a word list, like are you going to spell Electronic Mail
as email or e-mail, and so on. We also include terms on describing
components on the screen such as an option button, check box, drop-down
list, extc.

While it isn't typical of most style guides you might want to include
reference material for the programs that you are using and how you go
about a process. For instance, how do we create our help files or how to
create multimedia demos.

Be prepared for a lot of work and flexibility, but it can be well worth
it especially with for a new person just starting out. Our style guide
here is always changing, we continually review our style guide and make
any changes as necessary. A style guide is supposed to give a user a
good idea of how things are done and aren't normally carved in stone.

If you have any other questions, feel free to contact me. I hope this
helps and good luck.

Theresa Dunson
Technical Writer

*******************************************************

We bought the Microsoft Style Guide, looked through it for things we
disagreed with, changed those (they provide the guide in MS Word
format), added things that weren't covered, such as formatting styles
for hard copy and online and standard terminology, and then printed out
the whole thing when we were done.

Have fun. You've been given a lot of power if you do things right! :-)

-David Castro
 techwrtr -at- crl -dot- com

********************************************************

A while back (of course I can't remember when), there was a discussion
on techwr-l about style guides. You might want to check the archives.

I created the style guide for Epson and as you suspected, in-house style
guides are top secret so I can't send you a copy.  Sorry.

In general, I would not reinvent the wheel.  If your company already has
a standard (Chicago, Microsoft Manual of Style, Read Me First! (Sun),
refer to them in your style guide.  I spent a lot of time researching
how we use certain words and compiling a list (for example, we use
interface board instead of interface card).  I also spent a lot of time
documenting procedures.  Think about how you want to distribute the
style guide.

Right now, ours is distributed as hard copy or PostScript.  I want to
distribute it as PDF next.

We also have several FrameMaker templates we use and these were
documented separately.

I know this was very short.  Feel free to write back for more details or
to ask any questions.

Arlyn
arlyn_lee -at- ea -dot- epson -dot- com

**********************************************************

Our style guide is free for the asking.

Would you like HTML or MS Word?

Can you get attachments to email, or does
the text need to be embedded?

We do Distributed Object Software, but our
style guide is fairly generic.

Victor Chapel
victor -dot- chapel -at- trcinc -dot- com
The Technical Resource Connection
www.trcinc.com

***********************************************************

I would suggest contacting a company called Comprose, Inc.
(http://www.comprose.com) and see if you can purchase a copy of their
Documentation Blueprint (I believe it's $400-500). The product includes
over 100 copies of various documentation project forms--including those
for fonts, tags, etc. that would give you a great leg up on your
requirement.

And you're right, you *absolutely* need a style guide and quickly, even
if it's just for yourself. You can't remember every last detail and the
forms I mentioned can be the start of your style guide. Fill them in as
you have answers, worry about creating a *pretty* style guide later.

You also need to create (or, preferably, hire someone to create) a good
software tool that helps you implement the style guide decisions you've
made.

Please let me know if you have further questions. Style guides are
something I lecture about and beg my clients for, so I'm definitely in
your corner.

Sincerely,

Jerilynne Sander, President
Simply Written, Inc.
jsander -at- iquest -dot- net
317-578-9404

********************************************

I and a co-worker recently presented a paper at the STC conference
on developing a style guide. Depending on how big your company is
and how many resources you have to dedicate to this project, you
may want to consider buying a third-party style guide (I blush but
recommend one I worked on, _Read Me First_, which you may have seen
mentioned on the Techwr-l list) and issuing a supplement that
outlines places where your company either has specific requirements
or disagrees with recommendations in the commercial book.

-- Janice

********************************************

>My boss has asked me to work on creating a style guide for our
>documentation dept.
>
>1) Any suggestions on how to go about this?

My first suggestion is to think about what specific topics your style
guide needs to address because you don't want to duplicate the Chicago
Manual of Style if can help it.  My company's style guide has the
following sections:

Introduction - Purpose, general references, general guidelines

Rules - Corporate specific rules for acronyms, caps, hyphens,
illustration numbering, table numbering, etc.

Quick Word References - Corporate-specific rules for word usage,
particulary company products and equipment names.

IEEE Units and Symbols List - A list that our engineers have agreed to
abide by when writing the documentation.  You should try and find a list
of terms and abbreviations that fits your particular industry.

Misc. Procedures - Configuration Mgmt. procedures, illustration request,
etc.

You may be able to boil everything down into one or two sheets.  I
recommend you read "Sweat the Small Stuff -- Editing for Consistency" by
Vee Nelson in "Techniques for Technical Communicators", eds. Carol
Barnum and Saul Carliner. (Macmillan, 1993) ISBN 0-02-306095-6.  This
article shows you how to create a style sheet in a few easy steps while
you are writing.

I always reference the major works - Chicago Manual of Style, Webster's
Dictionary, Harbrace College Handbook, industry-specific dictionary,
etc., and let the corp. style guide handle the corp.-specific stuff.
>
>2) Does anyone know of a way I can look at another software company's
>in-house style guide, or are these top secret?

There are several corporate style guides in  print, including:

"The Microsoft Manual of Style" (Microsoft Press, 1995) ISBN
1-55615-939-0 $24.95. Microsoft specific of course, but well-written and
a good model to follow.

"The Digital Style Guide" (Digital Press, 1993) ISBN 0-13-0353379-5
$36.95. Good source of general rules and Digital Equipment specific
stuff as well.

"Xerox Publishing Standards" (Xerox Press, 1988) Out of print, but you
can find it in used book stores.  Written during the Ventura era, but it
does cover a lot of ground from planning to printing.  Dozens of
examples of Xerox document layouts.

Also, if you have access to the STC journal "Technical Communication"
and the magazine "Intercom", I think there have been several articles in
the past couple of years on how to develop a style guide.  Also back
issues of Editorial Eye at http://www.eeicom.com cover style guide
issues.

This should get you started. Good luck.


Tom Hoyt
Senior Technical Editor
QUALCOMM, Inc.
15286 SW 100th Ave.
Tigard, OR 97224
503-968-7201
thoyt -at- qualcomm -dot- com

*************************************************

Sun Microsystems put out a book called Read This First, which is a
genericized version of their style guide. It would be a good starting
point for you. For your own company, you should include things like
specific usage (and spelling and capitalization) of product names, any
particular phrases/phrasing that has meaning for your internal/external
audience, things to abbreviate a certain way (or certain abbreviations
not to use), required reading level (we shoot for grade 9), specific
page layout info (paper size, margins, fonts) for specific types of
documents... and a list of a lot of other stuff, but you get the idea.

If you're enamored of Microsoft, or just bowing to industry pressure,
you might consider using the Microsoft Manual of Style for reference; it
reminds me of the AP Style Guide, but aimed at the computer world, from
the MS viewpoint. If you're documenting Win95 applications, try Windows
Interface Guidelines for Software Design.

Hope this helps you get started.

Regards,

Guy Ivie
GuyI -at- corpmail -dot- follett -dot- com   (work)
givie -at- earthlink -dot- net   (not work)


--
******************************
Hillary Jones
hillary -at- nichimen -dot- com

******************************

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html