Re: Documentation process, style guide, intranet

Subject: Re: Documentation process, style guide, intranet
From: Eric Ray <ejray -at- raycomm -dot- com>
To: Linda Stark <lstark -at- ispchannel -dot- com>
Date: Mon, 13 Mar 2000 06:48:58 -0700

> Our side of the house is in better shape, mainly because the people who do
> the writing are better writers, but we have a real consistency problem. I'd
> like to come up with a documentation process for the company that emphasizes
> quality control. As I see it, the first thing we need is a company style
> guide. The places I have worked have all had style guides that ranged from a
> dog-earred piece of paper to a 1,000-page detailed manual with samples.
> (Which we really didn't follow because it wasn't updated and the info was
> out of date. In reality, you were supposed to learn the house style through
> osmosis.)

Well, I think you answered your own question...a company style guide,
particularly a monolith, isn't often useful, helpful, or used.
It is only significant or worthwhile when it answers
company/organization-specific questions or provides more accessible
and usable information than other available sources.

What you _need_ is a company style. Not a document--at least, not
yet. Start by coming to an agreement on an authoritive
dictionary and commercial style guide. Note that this isn't a big
deal or big decisions--whichever books most people already have
at work is probably as good a decision criterion as any,
because you're not looking for "right"--you're looking for

Absent any other information, I'd go for a Webster's Collegiate
dictionary and either Sun's Read Me First (if you're not a
MS-specific-software-shop) or the MS Manual of Style).
If you don't deal with software much at all, you might consider
Chicago Manual of Style for such issues (you can use it as a
fallback from the computer-industry books too).

Then, given that everyone now agrees on most (98%) of the style
issues, just document anything that deviates from or supplements
the guide. (For starters, documenting that stuff should be as
simple as emailing to all the writers and affected people
and stating "I think we should standardize on using DDoS
as the acronym for Distributed Denial of Service Attacks--everyone
OK with that?".) After you have a pile of notes, make them into
a document, but let the substance of the notes dictate what should
go into the document. It might be as short as a list of acronyms,
or as long as a book, but I'd bet on the former.

Keep in mind as you're choosing a style guide and making these
decisions that there is no right or wrong in terms of decisions.
Right = consistency and
wrong = inconsistency
Avoid the "Mrs. Grumby taught me to always/never use a serial
comma, so that's the only way I will write--if we've got to have
a style guide, it must say that" type discussions. They waste
everyone's time. Just make a decision and stick with it.

> I need some guidance (or an idea of where to look for the info) about how to
> plan a style manual. How much information should it include?

As little as possible.

> Or is it enough to make our house style guide cover just
> the things that are peculiar to the type of work we do? (A lot of it is
> government-related so acronyms are a real problem.) Is there any reason to
> cover more?

That's the approach.

Previous by Author: RE: Sites like
Next by Author: ADMIN: Duplicates and related admin stuff...important
Previous by Thread: RE: Documentation process, style guide, intranet
Next by Thread: Re: Documentation process, style guide, intranet

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

Sponsored Ads

Sponsored Ads