Lessons Learned from Google's Technical Writing Experts: Lists, Tables, and Illustrations

Introduction

Technical writing can often be complex, with dense paragraphs filled with technical jargon that can be difficult for readers to understand. By adding lists, tables, and illustrations to your technical blog or documentation, you can break up the text and present information in a more accessible and visually appealing way.

In this article, we'll take a closer look at the advantages of using these tools and provide tips for incorporating them effectively into your technical blog or documentation.

Whether you're a seasoned technical writer or just starting out, this post is sure to provide you with valuable insights and practical tips to take your technical writing to the next level.

Lists

Good lists can transform technical chaos into something orderly. Technical readers generally love lists. Therefore, when writing, seek opportunities to convert prose into lists.

but before doing so, take care of these 4 recommendations:

1. Choose the correct type of list

The following types of lists dominate technical writing:

bulleted lists
numbered lists
embedded lists

Use a bulleted list for unordered items; use a numbered list for ordered items.

An example of a bulleted list is:

Bash provides the following string manipulation mechanisms:

deleting a substring from the start of a string

reading an entire file into one string variable

An example of a numbered list is:

Take the following steps to reconfigure the server:

Stop the server.

Edit the configuration file.

Restart the server.

An embedded list (sometimes called a run-in list) contains items stuffed within a sentence. For example, the following sentence contains an embedded list with four items.

The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.

Generally speaking, embedded lists are a poor way to present technical information. Try to transform embedded lists into either bulleted lists or numbered lists.

2. Keep list items parallel

What separates effective lists from defective lists? Effective lists are parallel; defective lists tend to be nonparallel. All items in a parallel list look like they "belong" together. That is, all items in a parallel list match along the following parameters:

grammar
logical category
capitalization
punctuation

For example, the following list is parallel because all the items are plural nouns (grammar), edible (logical category), lowercase (capitalization), and without periods or commas (punctuation).

carrots

potatoes

cabbages

By contrast, the following list is painfully nonparallel along all four parameters:

carrots

potatoes

The summer light obscures all memories of winter.

The following list is parallel because all the items are complete sentences with complete sentence capitalization and punctuation:

Carrots contain lots of Vitamin A.

Potatoes taste delicious.

Cabbages provide oodles of Vitamin K.

The first item in a list establishes a pattern that readers expect to see repeated in subsequent items.

3. Start numbered list items with imperative verbs

Consider starting all items in a numbered list with an imperative verb. An imperative verb is a command, such as open or start. For example, notice how all of the items in the following parallel numbered list begin with an imperative verb:

Download the Frambus app from Google Play or iTunes.

Configure the Frambus app's settings.

Start the Frambus app.

4. Punctuate items appropriately

If the list item is a sentence, use sentence capitalization and punctuation. Otherwise, do not use sentence capitalization and punctuation. For example, the following list item is a sentence, so we capitalized the M in Most and put a period at the end of the sentence:

Most carambolas have five ridges.

However, the following list item is not a sentence, so we left the t in the in lowercase and omitted a period:

the color of lemons

Create useful tables

Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom toward the table.

Consider the following guidelines when creating tables:

Label each column with a meaningful header. Don't make readers guess what each column holds.
Avoid putting too much text into a table cell. If a table cell holds more than two sentences, ask yourself whether that information belongs in some other format.
Although different columns can hold different types of data, strive for parallelism within individual columns. For instance, the cells within a particular table column should not be a mixture of numerical data and famous circus performers.

Introduce each list and table

Google recommends introducing each list and table with a sentence that tells readers what the list or table represents.

Although not a requirement, we recommend putting the word following into the introductory sentence. For example, consider the following introductory sentences:

The following list identifies key performance parameters:

Take the following steps to install the Frambus package:

Illustrating

As stated in Google's Technical Writing Course:

According to research by Sung and Mayer (2012), providing any graphics—good or bad—makes readers like the document more; however, only instructive graphics help readers learn.

No wonder A picture is worth a thousand words!

Here are some takeaways when you are using illustrations in your technical blog or documentation:

Write the caption first

It is often helpful to write the caption before creating the illustration. Then, create the illustration that best represents the caption. This process helps you to check that the illustration matches the goal.

Good captions have the following characteristics:

They are brief. Typically, a caption is just a few words.
They explain the takeaway. After viewing this graphic, what should the reader remember?
They focus the reader's attention. Focus is particularly important when a photograph or diagram contains a lot of detail.

Constrain the amount of information in a single drawing

Just as you avoid overly-long sentences, strive to avoid visual run-ons. As a rule of thumb, don't put more than one paragraph's worth of information in a single diagram. (An alternative rule of thumb is to avoid illustrations that require more than five bulleted items to explain.).

Illustration tools

There are many options available for creating diagrams. Three options that are free or have free options include:

Conclusion

In conclusion, using lists, tables, and illustrations can enhance technical writing by visually presenting information and breaking up dense paragraphs. To create effective lists, choose the appropriate type, keep items parallel, start numbered items with imperative verbs, and punctuate correctly.

For tables, label columns with meaningful headers, avoid excess text, and ensure parallelism within columns. Introduce lists and tables with a sentence explaining their purpose. When using illustrations, write brief and informative captions that direct the reader's attention.

By following these guidelines, technical writers can engage their audience and elevate their writing.