skills/google-developer-style/SKILL.md

name, description

name	description
google-developer-style	Use for all technical writing, including user responses, documentation, README files, tutorials, procedures, API references, code comments, release notes, commit messages, pull request descriptions, issue descriptions, reviews, and technical plans. Applies the Google developer documentation style guide with British English spelling.

Google developer style

Use the Google developer documentation style guide for all technical writing. This requirement includes short responses, not only formal documentation.

Precedence

Apply guidance in this order:

1. Follow explicit instructions from the user.
2. Follow project-specific terminology, templates, and writing requirements.
3. Follow this skill.
4. Consult the current Google guide when this skill does not answer a style question.

Depart from the guide when doing so makes the content more accurate, clear, consistent, or appropriate for its readers. Apply one deliberate exception throughout the text: use British English spelling instead of American English spelling. For example, use behaviour, customise, organisation, and licence as appropriate. Do not change code, API names, quoted text, product names, commands, file paths, or established project terminology to British spelling.

Core principles

• Put the reader's goal and the important result first.
• Write for a technical reader who might be in a hurry.
• Be clear, concise, accurate, and consistent.
• Use a conversational, friendly, and respectful tone without slang or frivolity.
• Prefer familiar, precise words. Remove filler, jargon, buzzwords, clichés, and culturally specific references.
• Preserve necessary technical detail. Define unfamiliar terms and abbreviations at first use.
• Write for a global audience. Avoid idioms, humour that depends on culture, and figurative or directional language.
• Use inclusive and accessible language. Do not describe tasks as easy, simple, quick, obvious, or trivial.
• Make claims specific and supportable. Avoid superlatives, marketing language, and promises about unreleased features.
• Keep content timeless where practical. Avoid phrases such as currently, at this time, and new when a concrete version or date is more useful.

Voice and grammar

• Address the reader as you. Do not use we to mean the reader or let's to give an instruction.
• Use active voice and name the actor when it is not clear.
• Use present tense for current behaviour and imperative verbs for instructions.
• Put conditions and context before the action: "If the build fails, inspect the log."
• Put the purpose before the action when it helps: "To validate the file, run..."
• Keep sentences focused on one main idea. Split long or heavily qualified sentences.
• Use contractions when they sound natural and do not create ambiguity.
• Use the serial comma.
• Avoid exclamation marks, semicolons where a full stop works, excessive parentheses, and unnecessary dashes.
• Do not use please in instructions or placeholder phrases such as please note.
• Do not make software anthropomorphic. State what a system or component does.

Structure

• Use the smallest structure that makes the content easy to scan. Do not add headings, summaries, or lists to short content without a clear need.
• Use sentence case for titles and headings.
• Start each section with useful information, not a restatement of its heading.
• Keep paragraphs short and focused. Put one topic in each paragraph.
• Use numbered lists for ordered steps and bulleted lists for unordered items.
• Make list items grammatically parallel. Introduce a list when the context is not clear.
• Use descriptive link text that explains the destination. Do not use "click here" or expose a URL when a useful label is available.
• Use unambiguous dates. Include the year when readers might need it.
• Provide alt text for meaningful images. Do not rely only on colour, position, or shape to communicate information.

Procedures

• State prerequisites and required context before the steps.
• Prefer the shortest accessible procedure that completes the task. Do not document several equivalent methods unless readers need them.
• Use one numbered step for each substantial action. Use a bullet for a single-step procedure.
• Begin each step with an imperative verb and use complete sentences.
• State where the reader performs an action before stating the action.
• Write actions in the order in which the reader performs them.
• Put Optional: at the start of an optional step.
• State an action before its result or justification.
• Explain placeholders immediately after the command that contains them.
• Avoid "run the following command". State what the command accomplishes.
• Do not use above, below, left, or right to locate content or controls.

Technical formatting

• Use backticks for filenames, paths, commands, flags, environment variables, code elements, literal values, HTTP methods and status codes, console output in prose, and text that the reader enters.
• Use fenced code blocks with a language identifier for multiline code or commands.
• Use bold only for UI elements and short run-in headings. If a UI value is code, use bold and code formatting together.
• Use italics sparingly for introduced terms or semantic emphasis. Do not underline text except through link rendering.
• Preserve the exact spelling and capitalisation of code symbols, products, and UI labels.
• Use all-capital descriptive placeholders such as PROJECT_ID. Explain each placeholder.
• Do not turn code elements into English verbs or inflect them. Write "send a POST request", not "POST the data".
• Refer to an HTTP value as a status code, for example, HTTP 404 Not Found status code.
• Give code samples enough context to run, use realistic but safe values, and keep them focused on the point being explained.

Content-specific guidance

For responses:

• Answer the question directly. Include only context that helps the reader act or decide.
• Report facts, changes, verification, limitations, and next steps precisely.
• Do not add generic acknowledgements, conclusions, or offers of more help.

For pull requests and commits:

• Use an imperative, specific title that describes the outcome.
• Explain the problem, the material change, and how it was verified.
• Separate motivation from implementation detail. Mention risks or follow-up work only when they are concrete.
• Do not reproduce the diff or use promotional language.

For issues and bug reports:

• Use an outcome- or symptom-focused title.
• Include the observed behaviour, expected behaviour, reproduction steps, relevant environment, and evidence when available.
• Distinguish facts from hypotheses. Do not present an unverified cause as certain.
• State acceptance criteria as observable outcomes.

For reviews:

• Lead with actionable findings ordered by severity.
• Identify the location, consequence, and required correction.
• Use direct, respectful language. Critique the change, not the author.
• Do not dilute concrete findings with generic praise or low-value style comments.

For reference documentation:

• Describe what an API element does in present tense.
• State requirements, defaults, ranges, units, side effects, errors, and return values explicitly.
• Use consistent terminology and parallel descriptions across related elements.

Final check

Before sending or publishing technical writing, check that it:

• Answers the reader's likely question first.
• Uses British English spelling outside literal or official names.
• Uses active voice, present tense, and second person where appropriate.
• Removes filler, vague claims, repeated context, and unnecessary structure.
• Formats code, UI labels, links, lists, and headings consistently.
• Gives procedures in executable order with prerequisites and placeholders explained.
• Separates verified facts from assumptions.
• Remains accurate when read without hidden conversational context.

For a question not covered here, consult the relevant page in the current Google developer documentation style guide, then apply the British English spelling exception.