Lessons Learned from Google's Technical Writing Experts: Choose Your Words

Introduction

In the previous blog post, we explored how defining your audience, determining their needs, and fitting your writing to them are crucial steps in creating effective technical documentation. Now that we have a good understanding of our audience, it's time to focus on the actual writing itself.

In this blog post, we'll be diving into the nitty-gritty of technical writing, looking at how to choose words, write clear and concise sentences, and format our writing effectively.

These are all essential skills that can help us create documentation that is easy to read, understand, and use. So, let's get started!

Here are some of the things we would cover:

• Words

• Active voice Vs. Passive voice

Words

In technical writing, the words we use are crucial to conveying accurate and effective information. The language we choose impacts how our message is perceived and understood by our audience.

So, here are four tips recommended by Google's Technical Writing experts:

1. Define new or unfamiliar terms

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.

2. Use terms consistently

Here is a good analogy from Google's tech writing course:

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).

Here is an example of this:

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

Can you see the inconsistency in the above sentence? It's confusing to the readers to use it in one place Protocol Buffers and in another protobufs.

When writing, it's important to use consistent terminology to avoid confusion for your readers. This means avoiding the use of different terms to refer to the same thing within the same sentence or paragraph or even document. Doing so can lead to reader confusion and detract from the clarity of your writing.

3. Use acronyms properly

Using acronyms properly is important for effective communication. When using an unfamiliar acronym for the first time in a document or section, it is best to spell out the full term and put the acronym in parentheses. Both the spelled-out version and the acronym should be in boldface to make it easy for readers to identify the acronym. After the first use, you can use the acronym going forward.

Here is an example of how you should do it:

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.

Avoid cycling back and forth between the acronym and the expanded version in the same document as it may confuse the reader.

4. 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).

• 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.

By following these guidelines, you can avoid confusion and ensure that your writing is clear and easy to understand.

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 Golang?

Python is interpreted, while Golang 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

Also, this and that can cause problems and some ambiguity:

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.

Active voice

Using active voice in technical writing makes your writing more concise, direct, and easier to understand. While Passive voice can make your writing sound vague, wordy, and can obscure who is responsible for the action.

In technical writing, it's essential to be clear and precise, so active voice is often preferred.

Distinguish active voice from passive voice

Google Experts provide an excellent explanation to differentiate between active and passive voice, which you can access in their course here.

but in general, you can follow these formulas to distinguish the two of them:

Active Voice Sentence = actor + verb + target

Passive Voice Sentence = target + verb + actor

It is recommended to use the active voice most of the time, and sparingly use the passive voice. The active voice provides several advantages over the passive voice:

• readers tend to mentally convert passive voice to active voice, which can cause extra processing time. By sticking to the active voice, readers can skip the preprocessor stage and go straight to compilation.

• Passive voice can also obscure ideas and turn sentences on their head.

• Additionally, some passive-voice sentences omit an actor altogether, forcing the reader to guess the actor's identity.

• Active voice is generally shorter and more straightforward than passive voice.

Conclusion

In conclusion, choosing the right words, writing clear and concise sentences, and using active voice are all essential skills that can help you create documentation that is easy to read, understand, and use. Remember, the goal of technical writing is not to impress your readers with your vocabulary or writing style but to convey information in a way that is clear, concise, and easy to understand.

And don't forget to stay tuned for our upcoming blog, where we'll take another step and use the right words we chose to write clear sentences and paragraphs. Happy writing!