Technical content

In general, follow the guidelines in the grammar and mechanics section. If you come across anything not addressed there or here, use the Google developer documentation style guide as a reference.

Use the second person and tell users what to do. Be clear and to the point.

Unless there is a very good reason to do so, avoid using “we” and “our”.

For most types of documentation, especially in how-to guides, readers are following the instructions as they read. Use the present tense to describe actions. Similarly, avoid “would” and “could” (and any other modals expressing uncertainty) in conditional statements.

When inserting links into the text, try to give them descriptive text (not just the URL). Make exceptions for API endpoints when the purpose of including the link is to show the location of the endpoint.

Also avoid phrases such as “click here.” Have the text make sense out of context—when you’re looking just at the link text.

Keep computers and systems as inanimate things and attribute as few human qualities to them as possible.

Always be specific about what you’re referring to. If you introduce a specific product in the first sentence of a section, don’t assume the reader knows what you mean by “it” two paragraphs (or even two sentences later).

Repeat your references to make it clear what you’re talking about.

Any time you have long strings of nouns, break them up into smaller pieces so it’s clear what refers to what.

Numbered lists are a great sign to readers that steps need to be completed in a given order. They make it clear what steps need to be done when.

Don’t weaken this guidance by numbering other things where the order doesn’t matter. For example, headings in an article should follow a clear semantic structure. That structure should be enough, so the headings shouldn’t be numbered.

In keeping with our being empathetic, feel free to use common contractions. This means writing can’t and isn’t in place of cannot and are not.

It’s best to avoid shortening noun and verb combinations where it might be confusing (such as making readers think something is a possessive rather than a noun and verb). But common contractions such as it’s should be clear (just don’t confuse it’s and its).