Category Archives: language

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.

Delete or remove?

What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.

Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.

An example is the model of users and groups. Let’s say the user arthurdent belongs to two groups: spacers and earthlings. When Arthur no longer lives on planet Earth, you would remove arthurdent from the earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username arthurdent.

Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2.  So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.

Delete or remove

Works for me.🙂 What do you think?

Do you use singular or plural after “types of”

Would you say “two types of widget” or “two types of widgets”? In other words, should we use singular or plural after the phrase “types of”?

This is a real use case. In a code review this week, someone corrected my use of “types of widget”. People have varied and vociferous opinions. It’s intensely interesting, especially to technical writers.

Since I was a babe in arms, I’ve always used the singular:
“There are so many kinds of chocolate cookie! Which one shall I try next?”
“What are your favourite types of dog?”

To me this sequence just looks odd:
Pick one type of car.
Pick two types of cars.

Surely, if we can grant the English language a modicum of mathematical elegance😉 this should be correct:
Pick one type of car.
Pick two types of car.

So, why does the singular sound better to me? I think it’s because, when used after “types of”, the noun is acting as a concept representing a class of things, rather than a specific instance of the thing.

What do you think? Bring on the debate!

A kookaburra near my house:

A kookaburra looking goofy

What languages do our readers speak – from Google Analytics

I’ve grabbed some Google Analytics statistics about the languages used by visitors to the Atlassian documentation wiki. The information is based on the language setting in people’s browsers. It’s a pretty cool way of judging whether we need to translate our documentation!

The statistics cover a period of 3 months, from 7 September to 7 December 2012.

Summary

Approximately 30% of our readers speak a language other than English. The most popular non-English language is German (approximately 7%), followed by French (approx 2.6%). Japanese is hard to quantify, because we have separate sites for Japanese content.

The pretty picture

This graph shows the results for the top 10 locales:

Top 10 locales via Google Analytics

Top 10 locales via Google Analytics

The grey sector represents a number of smaller segments, each one below 1%. In Google Analytics, I can see them by requesting more than 10 lines of data.

The figures

Here are the figures that back the above graph:

Locale Number of visits Percentage of total
1. en-us 1,951,818 66.75%
2. en-gb 163,897 5.60%
3. de 105,526 3.61%
4. de-de 102,578 3.51%
5. fr 77,666 2.66%
6. ru 66,342 2.27%
7. zh-cn 38,850 1.33%
8. en 38,826 1.33%
9. es 37,129 1.27%
10. pl 30,064 1.03%

More Google Analytics?

Google Analytics is a useful tool. If you’re interested in a couple more posts about it, try the Google Analytics tag on this blog. I hope the posts are interesting.🙂

%d bloggers like this: