Blog Archives

Eliminating the zombie vulnerability – removing passive voice from the docs

If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.

Here are some examples of zombie-infested sentences, and their equivalents using active voice.

Example 1

Geographic requests are indicated by zombies through use of the coordinates parameter, indicating the specific locations passed by zombies as latitude/longitude values.

Converting passive voice to active:

You can use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

For an even more concise effect, use the imperative:

Use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

Example 2

Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Converting passive to active imperative:

Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Why eliminate the zombie vulnerability?

Active voice is more concise than passive voice. It’s usually easier to understand.

To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.

Who does what, in this example?

The API can return results restricted to a specific type. The restriction is specified using the types filter.

Answer: The developer has to specify the types in the types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.

The distinction between active voice and imperative mood

In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.

Should we ever invite zombies in?

I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?

These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.

Death of the gerund in technical documentation

Actually, I’m fond of the gerund myself. I’m not seriously proposing we kill it, but I’d love to know what everyone thinks about using, or not using, gerunds in headings and page titles.

A gerund is an “-ing” word, like “adding” or “removing”. More specifically, it’s the “-ing” form of a verb when used as a noun. Most technical documentation uses gerunds in topic titles and page headings, like this:

  • Adding a widget
  • Deleting a widget
  • Installing a widget

Examples of the traditional way:

Brave new world

We’re trying an experiment with short-form verbs in headings. Instead of gerunds, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page (using Ctrl+F, for example). It’s tempting to cite web searches as well, but any search engine worth its salt will find the stem of the word and return all results matching the stem.

Examples from our documentation:

  • Markers, in the Google Maps JavaScript API.
  • Map Objects, in the Google Maps Android API.

At the moment, we’re leaving gerunds in the page titles (primarily for consistency across the documentation suite) and just changing the headings within the pages.

Others who’ve killed the gerund:

Linguistics, IT and two trees

At university, I studied English with a strong emphasis on linguistics. This week a colleague at work, after reading my recent blog posts about language, let me know that she had studied linguistics too. So why are we both now in Information Technology (IT)? Also, John R made a thought-provoking comment. So now I’m following up on those two comments. And at the end, I’ll tell you how my trees are doing.

First of all, exactly why is this sentence funny or at least quirky: “Drive carefully when wet”?

Secondly, John R’s comment got me to thinking about how, with my fascination for linguistics, I ended up in IT. What makes a technical writer tick, and is the tick-mechanism anything like the widget that powers a systems engineer? Do John R (a self-professed ‘computationist’) and I (a linguaphile) actually share a habit of putting brackets around things and even indulging in the odd XOR?

Linguists have spent a lot of time trying to describe the knowledge common to speakers of a particular language. Without a shared knowledge, we wouldn’t be able to communicate. Some linguists think that there’s even an innate structural understanding shared by all humans, irrespective of which language they speak. So our brains come pre-wired with the “deep structural” rules of language, and we just have to plug in the specific language we need.

It seems fairly obvious that a language has a structure, and that all speakers of the language are able to manipulate the structure to produce unique, never-before spoken sentences with amazing ease. But describing the structure and its ability to generate new sentences has proved quite tricky.

Still, there’s hope. Take our sentence “Drive carefully when wet”. You might represent it like this:

sentence structure

Read the diagram starting from the top: A sentence (S) may consist of a noun phrase (NP) and a verb phrase (VP). A noun phrase may consist of a pronoun (Pro). A verb phrase may consist of a verb (V) plus an adverb (Adv) plus another sentence. And so on.

Linguists have also created a way to describe phrase-structure rules, complete with brackets and symbols to keep computationists 😉 happy. For example:

  • S –> NP VP (A sentence may consist of a noun phrase and a verb phrase)
  • NP –> Pro (A noun phrase may consist of a pronoun)
  • And so on.

And then you can add other logistical provisions, like:

  • “You” deletion: In an imperative sentence (i.e. a command), omit the “you”.
  • Pronoun matching: The second pronoun, also missing in our sentence, is assumed to be the same as the first pronoun.

……So…… that’s why it’s funny. Get it? 🙂

The design of computer languages, and other artificial languages, owes much to the work of linguists. Chomsky, in particular, is an easy mark. He’s the man everyone loves to shoot down. But his work on the theory of a universal grammar, transformational-generative grammars, the Chomsky hierarchy and the Chomsky normal form set the basis for much of what we do today.

So that may be why my colleague and I, linguists both, found our way into IT.

I think there are probably two sorts (or more 🙂 ) of people. Those like me, who seem to organise things into groups automatically (yeah, those brackets). The groupings are fluid and flexible, but the fact remains that we like them to be there. And then there are the people who float much more freely in their ecosystems: go with the flow, synchronicity rocks, hey man what’s the odd misplaced pronoun between friends?

Sometimes it amazes me how many different world views there are out there, just walking down the street next to me. And that we actually do manage to communicate with each other!

Moving on to my two trees:

Two months ago, I planted two trees. I promised a progress report every now and then. The trees are about the same age as this blog. And they’re doing great.

Here’s the paperbark, now 50cm high. (Was 40cm on 1 September.)

Paperbark

Here’s the old man banksia, now 32cm. (Was 17cm on 1 September.)

old man banksia

%d bloggers like this: