Grammar
Practical English Usage by Michael Swan (Oxford University Press) is a useful reference for questions on grammar.
Various types of bias may enter your writing including gender, race and disability. Not only is it thoughtless to ignore your readers' sensibilities but discrimination is also illegal. It is gender-neutral writing that presents the most grammatical challenges because English lacks gender-neutral singular pronouns suitable for describing people. For this reason, it is becoming more common to refer to people in the plural (they and their).
Although mixing singular and plural is also becoming more common, and has historical precedents (the user … their), many writers prefer to use consistent plurals (users … their) or second person (you … your). Most agree that he/she and its variants are clumsy and should be used only when the alternatives are less accurate or more cumbersome. Few advocate alternating between male and female in different sections or chapters.
Most technical writers prefer to use the active voice as much as possible, particularly in instructions. However, this does not mean that the passive voice is wrong. It is appropriate where the object acted on is more important than the agent that acted on it. Sometimes the agent is so irrelevant that it is omitted. A simple example conveys the difference in emphasis and information imparted.
The cat drank. (active)
You know what the cat did but not what was drunk.
The cat drank the milk. (active)
The emphasis is on the cat.
The milk was drunk by the cat. (passive)
The emphasis is on the milk.
The milk was drunk. (passive)
You know what was drunk but not what drank it.
If you were giving the cat an instruction, you would typically use the imperative: Drink!
A common example of a passive in software documentation is The New Customer dialog box is displayed. Putting this into the active voice requires one of:
- The New Customer dialog box displays.
British readers will expect it to display something, as display is a transitive verb.
- The New Customer dialog box appears.
Some writers argue this implies spontaneity rather than the result of a user action.
- The system displays the New Customer dialog box.
This gives redundant information and shifts the emphasis from the dialog box name.
Microsoft recommends
Use "appears" as an intransitive verb; use "displays" as a transitive verb. If necessary in context, you can use the passive "is displayed".
There is sometimes a case for using the imperative form for what the user does and the passive form for what the system does. This makes a clear distinction between the user's and the system's actions. We don't care, and sometimes don't know, what does the displaying.
Controlled languages like Simplified English may restrict the use of the passive voice. Simplified English also does not permit the use of display as a verb: a permitted alternative would be The New Customer dialog is shown on the display.
There appears to be a regional variation in attitudes to the passive voice. While both British and American writers agree that the active voice is better for most instructions, British writers are more likely to use the passive voice in other contexts than American writers (who are often taught to avoid it completely).
A split infinitive is when a word is inserted between the word to and the verb — as in the classic to boldly go. Most technical writers try to avoid splitting infinitives, unless the alternative is less clear or more cumbersome. The Concise Oxford English Dictionary states:
It is still widely held that splitting infinitives is wrong, a view based on an analogy with Latin. In Latin, infinitives cannot be split as they consist of only one word (e.g. amare 'to love'). It is therefore said that they should not be split in English either. But English is not the same as Latin, and the avoidance of a split infinitive can change the emphasis of a sentence or sound awkward (as in she seems really to like it). For this reason, the rule about avoiding split infinitives is not followed so strictly today, although it is best not to split them in formal writing.
"split infinitive n." The Concise Oxford English Dictionary, Eleventh edition revised . Ed. Catherine Soanes and Angus Stevenson. Oxford University Press, 2006. Oxford Reference Online. Oxford University Press. Syndicated edition for Institute of Scientific and Technical Communicators. 2 July 2007
|
