Re: Documentation process, style guide, intranet

[Eric Ray <ejray -at- raycomm -dot- com>]

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

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.