Google Technical writing notes

clarity.md

Clarity

Examples of strong verbs: triggers, issues, generates, specify, omit

• occured -> triggered
• happens when -> generates
• we are very careful to ensure that -> we carefully ensure
• a compiler error happens -> the compiler generates an error
• a variable declaration doesn't have a datatype -> you declare a variable but don't specify a datatype
• errors occur when you leave off a semicolon -> the compiler triggers an error/issues errors when you leave off a semicolon

Prefer active voice, specifying subject and object.

"There are/is" goes with general statements and can usually be dropped. If there is no subject, add one.

• There is a variable called met_trick that stores the current accuracy. -> The met_trick variable stores the current accuracy.
• There are two disturbing facts about Perl you should know. -> You should know two disturbing facts about Perl.
• There is no guarantee that the updates will be received in sequential order. -> Clients might not receive the updates in sequential order.

Avoid adjectives/adverbs, and use factual data instead:

• Setting this flag makes the application run screamingly fast. -> Setting this flag makes the application run 225-250% faster.

words.md

Words

https://developers.google.com/tech-writing/one/words

• Define terms as you introduce them, linking to good existing explanations where available
• Use terms consistently
• If using shorthand, introduce the shorthand "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."
• Don't cycle back and forth between acronyms and the expanded term
• Don't define acronyms that would only be used a few times.

When to use acronyms:

• The acronym is significantly shorter than the full term.
• The acronym appears many times in the document.

Style

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

  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.

Pronouns

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

Use either of the following tactics to disambiguate this and that:

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