Tuesday, July 27, 2010

Rules in Technical Documentation

Writing style of documentation can vary, depending on the product, and its target audience.

General English
General English follows standard grammatical conventions. Sentence length varies, but seldom are sentences longer than 25 words. Most sentences are simple or compound. Complex and compound-complex sentences appear infrequently. The vocabulary favors common straightforward words rather than more obscure words or nominalizations.

Formal English
Formal English uses more long complex sentences and complete grammatical constructions. Passive voice appears often, as do technical terms and nominalizations. Formal English may be appropriate for some technical material, but if the same sense can be conveyed by simpler general English, it should be. Sometimes a writer can lose track of correct grammar (say of subject-verb agreement) in convoluted formal English sentences.

Informal English
Informal English is breezy and journalistic. It's marked by short sentences, contractions, and directly addressing the user. Some grammatical constructions may not be complete. Informal English may be appropriate for some consumer products, but some attempts to be friendly can sound condescending.

Jargon
Jargon is a neutral term — it refers only to the technical language used by some particular profession or other group. It can be acceptable in the right context for a particular audience, where it serves as a shortcut to understanding concepts for those who understand the term.

Technical jargon is often acceptable in documentation for programmers and other technical audiences where you can assume a certain background or level of expertise. Marketing jargon and buzzwords generally are not acceptable. You can find a list of jargon in the index. Some of the terms are acceptable, especially in certain circumstances, and some are not.