There is extensive literature on good writing style, and this chapter is not intended to duplicate that literature. However, there are a few stylistic issues to discuss that relate directly to computer documentation.
In general, two principles underlie these stylistic considerations:
Straightforward, uncluttered writing is easier to understand and translate than more convoluted text. Keep sentences and syntax simple. Use short, familiar words. Respect a reader's level of technical knowledge and competency and make sure that your writing does not convey an arrogant or patronizing tone.
A reader expects you to be an expert on the subject or product discussed in your document. Write in a style that affirms your expertise. For example, too many sentences that include "you can" or "it is recommended" may confuse a reader who asks "but should I do this?" Instead, use imperative verbs that tell a reader accurately and concisely what to do. If you explain that a choice exists, describe for a reader the advantages and disadvantages of the alternatives, and make recommendations depending upon different scenarios.
One of the great temptations for writers of computer documentation is the urge to inject a note of levity into the text to relieve a reader's (or author's) uneasiness with the material. This temptation should be resisted - even genuinely humorous commentary is a distraction and will become annoying on subsequent readings. Many attempts at humor are likely to fail outright. Likewise, humor that descends into "user-friendly chumminess" never works. A sympathetic reader may forgive you for trying to "lighten up" the text, while another reader may resent a cloying tone.
For example, you might think that all readers will enjoy this humor injected into a tutorial:
You can use a mouse (one without fur) with the window environment on your computer.
However, "one without fur" detracts from the content of the sentence and distracts a reader.
Most importantly, humor is difficult (if not impossible) to translate successfully. Humor is strictly cultural; what may be funny to Americans could be obscene to readers in another country.
Writers frequently incorporate jargon associated with the subject matter into their documentation, in part to demonstrate their mastery of the subject, and in part because jargon adds "color" to documentation. This is another temptation that you should resist.
Jargon can be difficult for "non-initiates" to understand and will impede comprehension. Jargon also can be ambiguous; different fields of expertise can interpret the same jargon in different ways. Finally, jargon can be very difficult to translate.
For examples, the words listed below can be interpreted as valid computer terms or jargon used in the industry. If you use them, make sure that you, and the reader, understand their context and meaning in your document.
argument enter boot execute bring up floppy bundle getting help client help facility command interoperability comment out make up dataless mount default option diskfull power up/down diskless server end user string ------------------------------
Consistency is not just some abstract goal to be achieved for its own sake; rather, the intention is to reduce the impact of the mechanics of communication on readers. Readers project some significance onto every change in tone, language, or typographic convention you use. A consistent style enables readers to internalize the language and text conventions of a document so that understanding occurs on an almost subliminal basis, and so that truly significant points stand out more clearly. This is one of the most valuable aspects of good style. Refer to Chapter 8, "Constructing Text," for consistency guidelines.
One of the most important contributions a writer makes is to anticipate a reader's questions and provide appropriate answers. As the subject expert, a writer can create a climate of understanding that is far more significant than merely recounting facts about the product.
For example, when you review a procedure in your document with a reader's perspective in mind, ask these questions:
Regarding the issue of sexism in language - appearances count.
Writers who could never be described as sexist must be careful that their writing does not convey sexism. Equal opportunity in the workplace means that not all roles are filled by men. However, language has developed so that "men" often refers to "men and women," and that "he," "him," and "his" are regarded by some people as gender-neutral words. In decades past, this sentence would have been perfectly acceptable:
Ask your system administrator for his advice.
Today, the consistent usage of "he" and "his" is far less acceptable. These pronouns carry too much assumption about the sex of an individual. Writers who defend using such pronouns must contemplate this: Many readers will interpret a writer's intentions negatively, and consciously or subconsciously reject the work.
Your creative challenge is to eliminate not only the real sexism, but also the perceived sexism, from your writing. Stylistically, there are some boundaries.
Consider the following suggestions as ways to achieve common gender:
Awkward: Tell each user to shut down his machine.
Better: Tell the users to shut down their machines.
Awkward: Ask your system administrator for his advice.
Better: Ask your system administrator for advice.
Awkward: If the user decides he wants to change the settings . . . .
Better: If you want to change the settings . . . .
Awkward: If a system administrator installed the software, wait until he can help you.
Better: If a system administrator installed the software that you're having trouble with, wait until the administrator can help you.
Consider the following suggestions as somewhat daring:
This technique won't work for all types of documentation, but it can be effective in a tutorial or other type of user's guide. Consider naming names - obviously male or female - to humanize your writing and eliminate the "he or she" clumsiness.
For example, if you want to tell a user how to copy a file from someone else's directory, try this:
Before you can copy a file from someone else's directory - Sally Smith's, for example - you need permission. Ask Smith to set her file permissions to grant you access. After she has changed permissions,
you are free to copy the file.
Eliminating the appearance of sexism by writing poorly, ungrammatically, or self-consciously is not a good tradeoff. Keep the following in mind: