Technical Writing by Google

Only tips I am writing here which I think I am not doing in writing.

Tips

New words/Jargons

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.

Acronym

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.

Ambiguous Pronouns

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.

Problematic Pronouns: This, That, Them, They, It, Their

Prefer active voice to passive voice

Use the active voice most of the time. Use the passive voice sparingly. Active voice provides the following advantages:

Most readers mentally convert passive voice to active voice. Why subject your readers to extra processing time? By sticking to active voice, you enable readers to skip the preprocessor stage and go straight to compilation.

Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly.

Some passive voice sentences omit an actor altogether, which forces the reader to guess the actor's identity.

Active voice is generally shorter than passive voice.

Be bold—be active.

Use Strong verbs

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

Note that generic verbs often signal other ailments, such as:

an imprecise or missing actor in a sentence

a passive voice 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).

Short Sentences

Focus each sentence on a single idea. Focus each sentence on a single idea, thought, or concept. Just as statements in a program execute a single task, sentences should execute a single idea.

Convert some long sentences to lists

Eliminate or reduce extraneous words

Wordy	Concise
at this point in time	now
determine the location of	find
is able to	can

Reduce subordinate clauses:

Subordinate clauses modify the idea in the main clause. As the name implies, subordinate clauses are less important than the main clause. For example, consider the following sentence:

Python is an interpreted programming language, which was invented in 1991.
main clause: Python is an interpreted programming language
subordinate clause: which was invented in 1991

If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don't hear a pause, use that. Go back and read the preceding two example sentences. Do you hear the pause in the first sentence?

Place a comma before which; do not place a comma before that.

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

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.

Create useful tables

Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom towards 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.

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.

Focus each paragraph on a single topic

A paragraph should represent an independent unit of logic. Restrict each paragraph to the current topic. Don't describe what will happen in a future topic or what happened in a past topic. When revising, ruthlessly delete (or move to another paragraph) any sentence that doesn't directly relate to the current topic.

Answer what, why, and how

Good paragraphs answer the following three questions:

What are you trying to tell your reader?

Why is it important for the reader to know this?

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:

Audience

👉🏼

good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills

In other words, make sure your document provides the information that your audience needs but doesn't already have. Therefore, this unit explains how to do the following:

Define your audience.

Determine what your audience needs to learn.

Fit documentation to your audience.

Summarize key points at the start

Engineers and scientists are busy people who won't necessarily read all 76 pages of your design document. Imagine that your peers might only read the first paragraph of your document. Therefore, ensure that the start of your document answers your readers' essential questions.

Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of any long document is the hardest page to write. Be prepared to revise page one many times.

Compare and contrast

In your career, no matter how creative you are, you will author precious few documents containing truly revolutionary ideas. Most of your work will be evolutionary, building on existing technologies and concepts. Therefore, compare and contrast your ideas with concepts that your audience already understands. For example: