TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I've seen a lot of style guides, enough to know that what you mean by the
term may be quite different from what I mean. Some things should be
"rules," which the editor enforces; other things should be "guidelines,"
which the editor can question or argue with (on the grounds of readability
or usability) but cannot enforce.
Some style guides spend a lot of time on details of layout and design of at
least some documents, which should be enforced unless the writer can make a
very good case for doing it differently. If a company uses templates, the
style guide doesn't need to say anything other than "you will use the xxx
template for such-and-such a document type." That's an edict.
Some style guides specify things like what dictionary covers spelling, what
term is being used for what item (don't call it a widget in one place and a
gizmo in another), what will be in all caps or small caps, what
abbreviations are used, how equations are set out, etc. In other words,
picky stuff that is important for consistency but doesn't affect a writer's
"voice" or creativity. These are edicts. Some will be product- or
project-specific (eg terminology).
When the style guide gets into matters of word usage, sentence and
paragraph structure, and other aspects of literary style, it should be a
GUIDE, allowing the writer as much leeway as possible. Some matters are
appropriately edicts, because they may reflect on the company as a whole.
For example, the use of gender-inclusive language, or a variety of ethnic
names in examples, or not using humor, may be a requirement. However, the
grey area between what should be an edict and what should be a guide gets
really murky regarding literary style. As an editor, I've had to argue with
"grammatically correct" sentences that I was sure the reader would get lost
in, for example; but it's hard to make a rule about this.
I believe a style guide is essential if more than one person is working on
documentation for a project or a company, so that the results look and read
as if the company is well organized and knows what it's doing. Certainly
the tone of a user guide can be different from that of a reference manual,
but terminology should be consistent -- especially between the user guides
and the online help (often written by different people).
When I work as a contract writer for a company that has no staff writers, I
want to create a style guide so that on my next job with them, I can
quickly look up how I did things last time. If the company does have staff
writers, I very much need to know their style requirements so I can quickly
fit in.
Jane Bergen made some excellent points about the advantages of a style
guide to a staff writer, even when the only writer in a company.
Regards, Jean Weber
Sydney, Australia
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
