Re: Standardization for non-documentation documents

[Jim Purcell <jimpur -at- MICROSOFT -dot- COM>]

Patty Ewy asks:

> I have been given the task of helping set document standards for
> documents
> *other than* documentation that are produced by our company (right now
> only
> user manuals are considered "documentation" here, and as such are the
> only
> docs that have any standards whatsoever.)
>
> What I am looking for is information about what sorts of standards
> other
> companies have in place.  We need to start at ground zero here:  right
> now,
> we have "official" docs that have no date, no author, no revision
> number,
> etc.  I need to be able to outline requirements for all kinds of docs,
> from
> letters to customers to product specifications.
>
What are we talking about here: specifications, test plans, that sort of
thing? Or brochures, data sheets, white papers, and such like?

If the former, IEEE has a complete set of standards for documents
associated with the software development life cycle. I don't know of any
companies that follow these religiously, but they're a good starting
point. Check http://www.ieee.org for details. If you're not dealing with
software, check IEEE's many other standards documents, or look for a
standards body more relevant to what you are doing.

For marketing papers, look at what other companies are doing, find some
things you like, see if you can adapt them. Don't just steal stuff:
moral issues aside, you want people to identify your white papers with
your company. Using somebody else's format will undermine that goal.

As to standard front page stuff, decide what information you need and
make sure it's always there. Putting fields for this in a document
template is the surest way to make sure it isn't overlooked. A revision
history page in the front matter is always a good idea for evolving
documents.

> (BTW, if you have any hints
> about how to get others to buy off and actually *use* the standards,
> once
> set, that'd be great ...)
>
Do not expect the techies to embrace a new standard with open arms.
You're probably going to have to sell it, and you're probably going to
have to get management on board--and don't think that because they gave
you this assignment that they'll automatically be in your corner when
the engineers start to balk. Keep management in the loop as you develop
your standard, and make sure you have their buy-in. Keep engineering in
the loop, too; if they have input, they'll probably get a standard that
they and you can live with.

Two other things that can help: find one or two sympathetic engineers
with documents to write and help them through their first couple of
efforts. If you can report a success story starting out, the holdouts
will fall in line more easily. Also, automate as much as possible. Use
templates for major formatting, and use macros and automated keystroke
sequences to simplify routine tasks. Put unusual technical terms and
corporatespeak into the spell checker's dictionary. Thinking all this
stuff through beforehand will enhance your credibility. Making things
easy will speed acceptance of the standard.

> We have a style guide that we tech writers use--do other companies
> routinely
> require others in the company to follow the same guidelines?  What
> about
> revision history on things like product specifications--shouldn't
> there be a
> history summary at the end of each new release of a document that says
> how
> this version differs from the previous?
>
Before you define your style guide as the standard for design
documentation, make sure that's an appropriate thing to do. Style
decisions made in the interests of end users may not be right for
engineers addressing other engineers. Then think of how hard it is to
get writers to follow the style guide, and allow for an additional order
of magnitude of difficulty.

Good luck,

Jim Purcell
jimpur -at- microsoft -dot- com
My opinions, not Microsoft's

 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