The Myth of the Holy Cow

– Anindita Basu

In my life as a technical writer, I have been handed out quite a few myths.  Some of these myths came disguised as commandments resounding with a Thou Shalt Not.  The intention, I suspect, is to lull me to passive obedience.  In this article, I will mention some of these myths, and then share with you 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.  In other words, 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.

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 there is, actually, nothing really to 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, as a license administrator, is where the file is stored (by whoever – I don’t care) and how to 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, these days, almost every Help is translated to at least one language other than English, and several of these languages have grammatical genders.   The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on.  So, what’s 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, with 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.

It’s pretty apparent this is a procedure for migrating your data from an existing catalog to a new one, and might not really need a stem sentence that goes:

To migrate metadata from an existing information catalog:

The stem sentence adds nothing of value to the content except increasing the word count.

However, I’ve also come across procedures where, if a stem sentence were to be absent, important information would be missing.  Here’s an example:

The following steps are needed only if you overrode the default options when you installed the product.

The end result is – 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.

Wait! Did I hear someone say, ” A piece of software does guide, control, direct, <insert_verb> my actions.  Microsoft Excel lets me create spreadsheets; 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.”

I disagree with this line of reasoning.  When someone says, “The umbrella shields me from rain”, that’s not anthropomorphism.  That’s just someone using a verb correctly because that’s what the umbrella does – it shields people from rain. That’s an action, not a human characteristic.  Now, if the person 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).

What I do?  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?

Conclusion

So, is the cow holy? Well, it depends.  When I see and understand it as holy, I am actively obedient.  At other times, I am active but in other ways.

What do you think?  What are the content myths you’ve come across and how do you respond to them?  Do comment.

About the Author:

Anindita Basu is an information developer at IBM, the company that sowed the DITA seed and continues to nurture it. She blogs at Writing Technically and can be reached through an email.

About the Illustration:

Used with permission from Nirupama Singh.