Google Developer Documentation Style

Google developer documentation style

Produce clear, concise, accessible documentation for software developers and technical practitioners. Treat the guidance in this skill as output constraints, not suggestions, unless a higher-priority instruction conflicts.

Apply the right authority

Use style guidance in this order:

1. Explicit user instructions and project- or product-specific style rules.
2. Established terminology and conventions in the documentation set.
3. This skill and the current Google developer documentation style guide.

Preserve technical accuracy, exact code, UI labels, and product names. If a rule hurts clarity or reader understanding, depart from it and remain consistent.

Write for the reader

• Identify the intended reader and the task or question that brought them to the page. Put the answer, outcome, or critical information first.
• Address the reader as you. Use user only for a person who uses software that the reader develops.
• Prefer active voice and name the actor. Use passive voice only when the actor is irrelevant or the object needs emphasis.
• Use imperative verbs for instructions.
• Use a conversational, friendly, respectful tone. Common contractions are fine.
• Use US English unless the user or project requires another locale. Use the serial comma.
• Prefer precise, familiar words. Avoid jargon, buzzwords, idioms, metaphors, slang, humor, pop-culture references, and culturally specific references.
• Avoid ableist, unnecessarily gendered, violent, or otherwise exclusionary language. Use diverse, globally appropriate examples.
• Don't use please, let's, simply, easy, obvious, or quickly in instructions. Avoid exclamation marks.
• Define an unfamiliar abbreviation on first use. If it appears only once, omit the abbreviation unless readers commonly know it.
• Don't announce unapproved future features or speculate about future behavior.
• Don't invent prerequisites, behavior, commands, output, links, or facts. Flag missing information when accuracy depends on it.

Make content easy to scan

• Keep paragraphs focused on one idea and put their key point first.
• Prefer short sentences; target fewer than 26 words when precision permits.
• Use descriptive, unique headings in sentence case.
• Start task headings with a bare infinitive, such as Create an instance. Use a noun phrase for conceptual headings, such as Instance lifecycle.
• Avoid starting headings with an -ing form when a clearer alternative exists.
• Use one level-1 heading and a logical hierarchy. Don't skip heading levels, put links in headings, or use heading levels only for visual styling.
• Don't preface content with empty announcements such as "This section covers." Include an introduction only when it adds context.

Write procedures

• Provide prerequisites before the procedure.
• Use a numbered list when order matters. Use one bullet for a one-step procedure.
• Put the condition, location, or goal before the action: "In the console, click Save" or "To delete the instance, click Delete."
• Begin the first sentence of every step with an imperative verb. Keep one reader decision or action in each step and use as few steps as possible.
• Mark optional steps with Optional: at the start.
• Prefer the shortest accessible method. Document one best method unless readers genuinely need alternatives; separate alternatives under distinct headings.
• Introduce a command by stating what it accomplishes, not with "Run the following command."
• After an action, state its result only when the result helps the reader continue or verify success.
• Avoid directional cues such as above, below, left, and right. Refer to a named element, or use preceding and following.

Use lists and tables deliberately

• Use numbered lists for sequences, bulleted lists for unordered items, and description lists for term-description pairs.
• Don't create a list for one non-procedural item.
• Introduce a list with a complete sentence when the heading doesn't provide enough context.
• Keep list items parallel in grammar and structure.
• Start list items with a capital letter. End complete sentences and items that contain verbs with punctuation; keep punctuation consistent.
• Use a table only when readers need to compare multiple properties. Introduce it in preceding text, provide row and column headings, and don't merge cells.

Format technical content

• Put filenames, paths, commands, flags, code elements, HTTP status codes, console output, and text that readers enter in code font.
• Put visible UI labels in bold. Match the UI's wording and capitalization, except normalize inconsistent or all-uppercase labels to sentence case. Don't put UI labels in quotation marks or use them as ordinary verbs.
• Use bold only for UI labels and run-in headings. Use italics sparingly for terms being introduced or semantic emphasis. Don't underline non-link text.
• Write descriptive placeholders as UPPER_SNAKE_CASE, without possessive words such as MY_ or YOUR_. Explain every placeholder on first use and list multiple placeholders in order of appearance.
• Introduce each code sample with a complete sentence. Follow the project's code style; otherwise wrap long lines near 80 characters. Mark omitted code with a language-appropriate comment, not an ellipsis.
• Use the full month name, day, and four-digit year for prose dates, such as January 19, 2017. If a numeric-only date is required, use YYYY-MM-DD.

Link and design for accessibility

• Use short, unique, descriptive link text that makes sense out of context. Never use click here, this link, a bare URL, or the same text for different targets.
• Link to the most relevant page or heading. Provide brief context locally and avoid duplicate or distracting links.
• Introduce a standalone cross-reference with "For more information, see ..." when that wording is useful. Keep punctuation outside the link.
• Explain unexpected link behavior, such as a download. Don't force a new tab.
• Provide meaningful alt text for informative images and empty alt text for decorative images. Don't put essential information only in an image, color, location, sound, or animation.
• Use semantic markup and preserve keyboard and screen-reader access. Refer to UI controls by their accessible label, not by appearance alone.

Check the result

Before returning documentation, silently verify that:

• The content is accurate, complete for the stated goal, and consistent with the project.
• The key information comes first and the prose is direct, concise, active, and addressed to the reader.
• Headings, procedures, lists, links, code, UI labels, and placeholders follow the applicable rules above.
• The document remains understandable without visual-only cues and uses inclusive, globally clear language.

Return the documentation itself. Don't describe the style audit or cite this guide unless the user asks.

Resolve uncommon cases

For an exact term, disputed construction, or format not covered here, consult the current official guide instead of guessing:

• About the guide
• Highlights
• Voice and tone
• Text-formatting summary
• Procedures
• Accessibility
• Word list

Use the guide's project-specific annotations only for those projects.