In my life as a technical writer, I have been handed out quite a few myths [A myth, says the Oxford dictionary, is a traditional story], myths that come disguised as commandments that resound with a Thou Shalt Not. The intention, I suspect, is to lull me to passive obedience. In this blog post, I will mention some of these myths and what I think (and do) about them.
Passive voice has no place in technical writing
Before I state my position on this myth, let us recollect the definition of
voice: the form of the verb that shows the relation of the subject to the action. So, the voice of a sentence shows whether the subject actively took ownership of an action and did it, or was so passive as to only be the recipient of the effects of the action.
 |
| Picture source: http://www.chumpysclipart.com/illustration/1199/picture_of_a_soccer_referee_being_hit_on_the_back_of_the_head_with_a_soccer_ball |
Now let us look at the structure of a very simple sentence expressed both in active and passive voice.
Active: The installer copied the WAR files to the installation directory.
Passive: The WAR files were copied to the installation directory.
This example is a simple example and I wouldn't really prefer one voice over the other. But, consider the following example:
License key definitions are stored in a license key file, which, by default, is named lkad.dat and located in the product installation directory. If you need to modify the list of authorised servers or users, edit the license key file with any text editor.
Is there any reason why the first sentence needs to be turned into the active voice? Is there any reason why I want to know who is doing the storing action? All I want to know, if I am a license administrator, is where the file is stored (by whoever – I don’t care), what it is named, and how I can edit the license definitions it contains. Passive voice works here, and marvellously.
Upshot: When I think the doing of an action is important, I write in active voice. When I think it doesn’t matter who or what did or caused the action so long as the action got done, I don’t spend any time changing a passive voice construction to active.
Writing must be gender neutral
With all respect to all kinds of genders on this earth, I think that’s a piece of unholy baloney. In English, there is no grammatical gender. But, even though we write in English, there's every likelihood that the text will be translated to at least one language other than English. Many of these non-English languages have grammatical genders. The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on. So, something that is gender neutral in English can very well turn into a gendered phrase in a language like, say, French or Hindi.
My take is that spending anything more than 5 minutes on rephrasing an otherwise understandable and acceptable-by-usage English sentence into a gender-neutral sentence is nothing but a waste of time.
Every list should be preceded by an introductory sentence
The logic is, if I suddenly start a numbered list that has steps to perform a specific task, but do not introduce the list with a stem sentence, readers might be misled, confused, misinformed, etc.
Now, let’s see the following example:
1. Use one of the following methods to start the Manage Information Catalog wizard:
* From the Windows desktop, click Start > IBM DB2 > Set-up Tools > Manage Information Catalog wizard.
* At a command prompt, enter db2iccwz.
The Manage Information Catalog wizard opens.
2. Select the Migrate metadata from an existing information catalog option.
3. Enter the required information on each page of the wizard and click Finish.
To me, it is apparent this is a procedure for migrating your data from an existing catalog to a new one. To my users, who are undoubtedly smarter than me because they are database administrators [audience, audience], it is very apparent that this is a procedure for migrating data from an old catalog to new; my users just do not need a stem sentence that goes:
To migrate metadata from an existing information catalog:
The title of the topic would, in any case, always have an indication of what is contained in the topic. The stem sentence adds nothing of value to the content except increasing the word count.
However, I have also come across procedures where, if a stem sentence were to be absent, important information would be missing. Here is an example:
The following steps are needed only if you overrode the default options when you installed the product.
The end result – I leave out stem sentences if I think there’s no value add in having them.
Leave the comparatives and the adverbs alone
I am in complete agreement. Whether an application is
quickly installed,
easier to use, and
fastest in terms of response time is a conclusion best left to the user to arrive at. Technical writers are supposed to report facts, not hand out value judgements.
Computers (and computer applications) do not possess human characteristics, so, do not anthropomorphise them
I agree.
Did I hear someone say, " A piece of software does guide, control, direct my actions. Microsoft Excel lets me create spreadsheets but it does not let me create documents. An umbrella shields me from rain; a car gets me from point A to point B. It’s perfectly okay to anthropomorphise."
 |
| Picture source: http://www.wpclipart.com/cartoon/animals/fish/fish_with_umbrella_cartoon.png.html |
I disagree with this line of reasoning. When someone says, "The umbrella shields me from rain", that is not anthropomorphism. That’s just someone using a verb correctly because that is indeed what an umbrella does – it shields people from rain. That is an action, not a human characteristic. Now, if someone were to say, "My brave umbrella valiantly tries to shield me from rain but fails", now that, my friend, is anthropomorphism because the umbrella has become possessed of the human characteristic of braveness (and chivalry, perchance).
Me? I let my software
detect conflicts and
resolve them but I do not expect it to be
remorseful when it crashes my desktop.
A procedure should not have more than 7 steps
If anything takes more than 7 steps, says the stricture, break the procedure up into smaller logical pieces. I am guessing this comes from the assumption that readers have short attention spans. I said "guessing" because though I’ve been told there are studies that prove a decrease in comprehension levels after Step 7, I am inclined to believe if someone’s life depended on it, that person would read even
War and Peace from cover to cover.
That said, I do try to keep my procedures as short as possible. But, sometimes, the products we write for do have procedures that cannot be fitted into the 7-step-frame. For example, can the instructions to install a rack-mounted server system really be covered in 7 steps? Really?
Conclusion
So, is the cow holy? Well, it depends.
[A slightly different version of this blog post was published in STC India's magazine INDUS.]
