Lessons Learned from Google's Technical Writing Experts: Clear, Short Sentences and Paragraphs

Introduction

In our previous blog post, we explored some key tips for effective technical writing, including choosing the choosing right words and using the active voice in our sentences.

In this article, we delve deeper into the subject by examining how Google's technical writing experts approach crafting clear sentences and paragraphs. These tips can help you communicate complex ideas more effectively and improve the overall clarity of your writing.

So, let's take a closer look at the lessons learned from Google's experts on how to write clear sentences and paragraphs.

This article would cover:

• Clear Sentences.

• Short Sentences.

• Paragraphs.

Note: this article draws heavily from Google's Technical Writing Course, which provides excellent resources on this topic.

---

Write Clear Sentences

Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest.

Choose strong verbs

As mentioned in Google's Technical Writing Course, "Many technical writers believe that the verb is the most important part of a sentence. Pick the right verb and the rest of the sentence will take care of itself."

Unfortunately, some writers reuse only a limited range of weak verbs, which is like offering your guests the same dull and unappetizing food every day. While selecting the appropriate verb may take a little more effort, it can yield more enjoyable outcomes.

To engage and educate readers, choose precise, strong, specific verbs. Reduce imprecise, weak, or generic verbs, such as the following:

• forms of be: is, are, am, was, were, etc.

• occur

• happen

For instance, consider how strengthening the weak verb in the following sentences ignites a more engaging sentence:

Reduce there is / there are

Sentences that start with There is or There are marry a generic noun to a generic verb. Generic weddings bore readers. Show true love for your readers by providing a real subject and a real verb.

In the best-case scenario, you may simply delete There is or There are (and possibly another word or two later in the sentence). For example, consider the following sentence:

• There is a variable called met_trick that stores the current accuracy.

Removing There is replaces the generic subject with a better subject. For example, either of the following sentences is clearer than the original:

• A variable named met_trick stores the current accuracy.

• The met_trick variable stores the current accuracy.

You can sometimes repair a There is or There are sentence by moving the true subject and true verb from the end of the sentence to the beginning. For example, notice that the pronoun you appears towards the end of the following sentence:

There are two disturbing facts about Perl you should know.

Replacing There are with You strengthens the sentence:

• You should know two disturbing facts about Perl.

In other situations, writers start sentences with There is or There are to avoid the hassle of creating true subjects or verbs. If no subject exists, consider creating one. For example, the following There is sentence does not identify the receiving entity:

• There is no guarantee that the updates will be received in sequential order.

Replacing "There is" with a meaningful subject (such as clients) creates a clearer experience for the reader:

• Clients might not receive the updates in sequential order.

---

Write Short Sentences

Short sentences communicate more powerfully than long sentences and short sentences are usually easier to understand than long sentences. Yes, finding the shortest documentation implementation takes time but is ultimately worthwhile.

Here are 4 advice that will help you to write short sentences:

1. Focus each sentence on a single idea

The key to writing clear and effective sentences is to focus each sentence on a single idea, thought, or concept. This is similar to how statements in a program execute a single task.

For example, the following very long sentence contains multiple thoughts:

In bash, use the if, then, and fi statements to implement a simple conditional branching block in which the if statement evaluates an expression, the then statement introduces a block of statements to run when the if expression is true, and the fi statement marks the end of the conditional branching block.

Breaking the long sentence into a succession of single-idea sentences yields the following result:

In bash, use an if, then, and fi statement to implement a simple conditional branching block. The if statement evaluates an expression. The then statement introduces a block of statements to run when the if expression is true. The fi statement marks the end of the conditional branching block. (The resulting paragraph remains unclear but is still much easier to read than the original sentence.)

2. Convert long sentences to lists

When you see the conjunction or in a long sentence, consider refactoring that sentence into a bulleted list. When you see an embedded list of items or tasks within a long sentence, consider refactoring that sentence into a bulleted or numbered list.

To alter the usual flow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement (which skips past the remainder of the current iteration of the current loop).

For example, the preceding example contains the conjunction or, so let's convert that long sentence to the following bulleted list:

To alter the usual flow of a loop, call one of the following statements:

• break, which hops you out of the current loop.

• continue, which skips past the remainder of the current iteration of the current loop.

Note: Lists are an important topic in technical writing, and there is an article dedicated to their use that can be found here.

3. Eliminate or reduce extraneous words

Many sentences contain filler—textual junk food that consumes space without nourishing the reader.

For example, see if you can spot the unnecessary words in the following sentence:

An input value greater than 100 causes the triggering of logging.

Replacing causes the triggering of with the much shorter verb triggers yields a shorter sentence:

An input value greater than 100 triggers logging.

The following table suggests replacements for a few common bloated phrases:

With practice, you'll spot the extra words and feel enormous happiness in removing or reducing them.

---

Paragraphs

While paragraphs are made up of sentences, they have their own unique properties that contribute to effective communication. In this section, we'll delve into the key elements of effective paragraphs in technical writing.

Here are 3 advice for writing great paragraphs:

1. Write a great opening sentence

The opening sentence is the most important sentence of any paragraph. Busy readers focus on opening sentences and sometimes skip over subsequent sentences. Therefore, focus your writing energy on opening sentences.

Good opening sentences establish the paragraph's central point. For example, the following paragraph features an effective opening sentence:

A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.

The preceding opening sentence establishes the theme of the paragraph as an introduction to loops. By contrast, the following opening sentence sends readers in the wrong direction:

A block of code is any set of contiguous code within the same function. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.

2. Focus each paragraph on a single topic

A well-crafted paragraph should represent a self-contained unit of logic that focuses solely on the current topic. It should not discuss past or future topics, and any sentences that do not directly contribute to the main idea should be removed or placed in another paragraph. In this way, paragraphs help to maintain clarity and coherence in your blog/documentation.

Here is an example from Google's Technical Writing Course:

Assume that the opening sentence of the following paragraph does focus on the correct topic. Can you spot the sentences that should be removed from the following paragraph?

The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.

We've crossed out the second and fifth sentences to yield a paragraph focused exclusively on the Pythagorean Theorem:

The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.

3. Don't make paragraphs too long or too short

Long paragraphs are visually intimidating. Very long paragraphs form a dreaded "wall of text" that readers ignore. Readers generally welcome paragraphs containing three to five sentences but will avoid paragraphs containing more than about seven sentences. When revising, consider dividing very long paragraphs into two separate paragraphs.

Conversely, don't make paragraphs too short. If your document contains plenty of one-sentence paragraphs, your organization is faulty. Seek ways to combine those one-sentence paragraphs into cohesive multi-sentence paragraphs or possibly into lists.

Answer what, why, and how

Good paragraphs answer the following three questions:

1. What are you trying to tell your reader?

2. Why is it important for the reader to know this?

3. How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?

For example, the following paragraph answers what, why, and how:

<Start of What>The garp() function returns the delta between a dataset's mean and median.<End of What> <Start of Why>Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points.<End of Why> <Start of How>Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp() value suggests that the mean is more meaningful than when the garp() value is relatively high.<End of How>

---

Conclusion

In conclusion, effective technical writing is critical for communicating complex ideas and information to a wide range of audiences. Writing clearly and concisely can improve the comprehension and retention of technical information, reducing errors and improving productivity.

In this article, we have discussed several tips and techniques to help you write blogs / technical documents that are clear, concise, and engaging. By choosing strong, specific verbs, focusing on a single idea in each sentence, eliminating unnecessary words, and structuring your paragraphs effectively, you can create technical documents that are easy to understand and that effectively convey your message to your intended audience.

Remember, effective technical writing takes practice, so don't be afraid to edit and revise your work until you achieve the clarity and simplicity necessary for successful communication.