Words

We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words.

Define new or unfamiliar terms

When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. When you spot such a term, take one of the following two tactics:

  • If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.)
  • If your document is introducing the term, define the term. If your document is introducing many terms, collect the definitions into a glossary.

Use terms consistently

If you change the name of a variable midway through a method, your code won’t compile. Similarly, if you rename a term in the middle of a document, your ideas won’t compile (in your users’ heads).

The moral: apply the same unambiguous word or term consistently throughout your document. Once you've named a component thingy, don't rename it thingamabob. For example, the following paragraph mistakenly renames Protocol Buffers to protobufs:

Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

George Fairbanks, a Google software engineer, provides this excellent note about consistent naming:

When I encounter two words that seem to be synonyms, I wonder if the author is trying to signal a subtle distinction that I need to track down and understand.

Yes, technical writing is cruel and restrictive, but at least technical writing provides an excellent workaround. Namely, when introducing a long-winded concept name or product name, you may also specify a shortened version of that name. Then, you may use that shortened name throughout the document. For example, the following paragraph is fine:

Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

Use acronyms properly

On the initial use of an unfamiliar acronym within a document or a section, spell out the full term, and then put the acronym in parentheses. Put both the spelled-out version and the acronym in boldface. For example:

This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.

You may then use the acronym going forward, as in the following example:

If no cache entry exists, the Mixer calls the OttoGroup Server (OGS) to fetch Ottos for the request. The OGS is a repository that holds all servable Ottos. The OGS is organized in a logical tree structure, with a root node and two levels of leaf nodes. The OGS root forwards the request to the leaves and collects the responses.

Do not cycle back-and-forth between the acronym and the expanded version in the same document.

Use the acronym or the full term?

Sure, you can introduce and use acronyms properly, but should you use acronyms? Well, acronyms do reduce sentence size. For example, TTN is two words shorter than Telekinetic Tactile Network. However, acronyms are really just a layer of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers convert TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to process than the full term.

Heavily used acronyms develop their own identity. After a number of occurrences, readers generally stop expanding acronyms into the full term. Many web developers, for example, have forgotten what HTML expands to.

Here are the guidelines for acronyms:

  • Don't define acronyms that would only be used a few times.
  • Do define acronyms that meet both of the following criteria:
    • The acronym is significantly shorter than the full term.
    • The acronym appears many times in the document.

Exercise

Fix the following passage. Assume that this passage is the initial instance of the term MapReduce in the document and that MR is the best abbreviation.

Jeff Dean invented MapReduce in 1693, implementing the algorithm on a silicon-based computer fabricated from beach sand, wax-paper, a quill pen, and a toaster oven. This version of MR held several world performance records until 2014.

(Please note that the preceding passage is meant to be humorous, not factual.)

Recognize ambiguous pronouns

Many pronouns point to a previously introduced noun. Such pronouns are analogous to pointers in programming. Like pointers in programming, pronouns tend to introduce errors. Using pronouns improperly causes the cognitive equivalent of a null pointer error in your readers’ heads. In many cases, you should simply avoid the pronoun and just reuse the noun. However, the utility of a pronoun sometimes outweighs its risk (as in this sentence).

Consider the following pronoun guidelines:

  • Only use a pronoun after you've introduced the noun; never use the pronoun before you've introduced the noun.
  • Place the pronoun as close as possible to the referring noun. In general, if more than five words separate your noun from your pronoun, consider repeating the noun instead of using the pronoun.
  • If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.

It and they

The following pronouns cause the most confusion in technical documentation:

  • It
  • They, them, and their

For example, in the following sentence, does It refer to Python or to C++?

Python is interpreted, while C++ is compiled. It has an almost cult-like following.

As another example, what does their refer to in the following sentence?

Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending.

This and that

Consider two additional problem pronouns:

  • This
  • That

For example, in the following ambiguous sentence, This could refer to the user ID, to running the process, or to all of these:

Running the process configures permissions and generates a user ID. This lets users authenticate to the app.

To help readers, avoid using this or that in ways where it's not clear what they refer to. Use either of the following tactics to clarify ambiguous uses of this and that:

  • Replace this or that with the appropriate noun.
  • Place a noun immediately after this or that.

Substitute or add explicit terms as needed, as in the following rewrites of the example's second sentence:

This user ID lets users authenticate.

The process of configuring permissions lets users authenticate.

The combination of permissions and a user ID lets users authenticate.

Exercise

Identify all possible meanings for the ambiguous pronouns in each of the following passages:

  1. Aparna and Phil share responsibilities with Maysam and Karan and they are next on call.

  2. You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk.


Next unit: Active voice