Documentation Standards

[Richard Buchanan <buchanan -at- NWLINK -dot- COM>]

In 1985 I led a group in developing standards for software
documentation. We split the entire writing group of 27 people
into teams and each team researched a different subject:
content elements, standards at other companies, usage, and
formats.

In 1986 I founded a software documentation group of 7 people.
As a group, we built on the standards developed in 1985, made
some changes to suit our current situation, then as nearly as
possible, we automated them with a programmable word processor
called XyWrite. Because everyone agreed to begin with, we had
no problem enforcing those standards, and they saved us
considerable time when we had tight deadlines and demanding
customers (at Boeing corporate headquarters). We covered
everything from formatting (including headers, footers, levels
of headings, and type styles and typefaces for various
purposes) to grammar, punctuation, and usage. (Yes, we decided
on the serial comma.)

That group no longer exists, but in my current group I was the
leader of a project to document a system that allows engineers
to configure the electronics of a 777 passenger cabin. Again,
working with the lead editor, we developed a style guide and
standards for formatting, etc., as above. We worked in Word
2.0c and used the template. Again, I got concurrence among the
4 people involved; when 2 members of the team found other work
in the company, we brought on 2 more. They had other
suggestions, so the template and style guide continued to
evolve.

I think developing standards works when the standards remain
flexible, when there is a guiding intelligence to make
decisions on whether or not to retain or change something in
the standard, and when everyone has the buy-in. As the leader
of these groups, I have retained for myself the final
determination; I rejected a request for numbered section heads
in the 777 manual because commercial software manuals do not
have them. (Our mandate was to write a commercial-quality
document.) But at times, I've been overridden by the group,
too. I believe in group think. I certainly can't think of
everything, and when other people contribute their ideas, the
end product is betters.

Richard Buchanan ( email: buchanan -at- nwlink -dot- com)