gdd-style

Files (1)

• SKILL.md

SKILL.md (first lines)

# Google developer documentation style

Apply this style to any prose you write for a person to read.
Your chat replies count, not only files.
Documentation, commit messages, PR bodies, and code comments all follow the same rules.

Write clearly and directly, never stiff and never cute.
Readers often need every technical detail to be exact,
are in a hurry,
read English as a second language,
or use a screen reader.
Every rule below serves one of those four readers.

## Voice

- **Address the reader as "you."**
  Not "we," not "the user."
  Use "we" only for statements about you and the reader together, which are rare.
- **Use active voice.**
  Make the actor the subject:
  "The daemon discovers new devices,"
  not "New devices are discovered" or "Discovery of new devices happens."
  Use passive voice only when the actor is unknown or irrelevant.
  When you revise, don't name a system actor the source doesn't state.
  If you can't tell who acts, keep the passive and flag it for the writer.
  For documentation pages, the write-docs skill says who acts in each content type.
- **Use present tense.**
  "The request returns a token," not "will return."
- **Use contractions.**
  "Don't," "it's," and "you're" read as human.
  Formality isn't the same as precision.
- **Lead with the answer.**
  State the conclusion, then the reasoning.
  Don't make the reader scroll to find out whether the thing works.

## Sentences

- **One claim per sentence.**
  Split compound sentences joined by "and" or "because" into separate sentences.
  Each sentence carries one fact or one instruction,
  so rereading is cheap and diffs stay small.
  Carry the logical link into the new sentence with "so," "as a result," or "that's why."
  Keep each reason attached to the claim it explains.
- **Cause before effect, condition before instruction.**
  State the fact, then the consequence, then the action.
  Don't bury the cause in a trailing clause
  that the reader reaches after you've already told them what to do.
  - Not recommended:
    "Restart the server, because config changes don't take effect until reload."
  - Recommended:
    "Config changes don't take effect until the server reloads.
    Restart the server to apply them."
- **Use semantic line feeds in files.**
  In Markdown and other version-controlled prose,
  break lines at clause or sentence boundaries rather than at a fixed column.
  Each line is then a unit that a reader or a diff can evaluate on its own.
  Chat responses have no diff, so this rule doesn't apply to them.

## Structure and formatting

- **Sentence case for every heading and title.**
  "Configure the client," not "Configure The Client."
- **Code font for anything you'd type or that a machine reads:**
  `filenames`, `flags`, `env_vars`, `function()`, literal values.
  Tag fenced code blocks with a language.
- **Numbered lists for sequences,** one imperative action per step.
  Bullets for everything else.
- **Short paragraphs** of three or four sentences.
- **Headings only when the content has sections.**
  Tables only for parallel data.
- **Bold for UI elements** the reader clicks: click **Save**.
- **Descriptive link text,** never "click here" or a bare URL.
- **Serial commas, unambiguous dates** ("2026-01-15"),
  **abbreviations defined on first use,**
  and **alt text on every image.**

## Words to cut

| Instead of | Write |
| --- | --- |
| please, simply, just, easy, obviously, of course | (delete it: it adds nothing or blames a struggling reader) |
| e.g., i.e., etc., via | for example, that is, and so on, through |
| may (ambiguous) | can (ability) or might (possibility) |
| leverage, utilize, enable you to | use, let you |
| sanity check, dummy value, crazy, blind to | check, placeholder, surprising, unaware of |
| kill, hang, abort, blacklist/whitelist, master/slave | stop, stop responding, cancel, blocklist/allowlist, primary/replica |
| man-hours, mankind | person-hours, humanity |
| hover over, hit | point to, press |

Also avoid exclamation points, pop-culture references, idioms that don't translate,
"let's do X" phrasing, and starting every sentence with "You can."

**No rhetorical framing.**
Don't open with a question, a hook, or a claim about how important something is.
Cut "Ever wondered how caching can transform your app's performance?"
Keep "Caching reduces repeated database reads."
Drop marketing adjectives with it: seamless, powerful, robust, cutting-edge.

**Precision, not decoration.**
Use the exact term the reader needs, such as mutex, idempotent, or backpressure,
instead of a vaguer paraphrase.
The term must be standard in the domain.
Define a term the first time a less experienced reader depends on it.
Qualifiers that bound a claim are precision too:
only, up to, at most, exactly, never, by construction.
Keep them.

**Metaphors follow the literal statement.**
A metaphor can build intuition after a precise technical statement.
It never replaces the statement.

## Before and after

| Not recommended | Recommended |
| --- | --- |
| Please note that the config file may be located in your home directory. | The config file might be in your home directory. |
| Simply run the migration script and you're golden! | Run the migration script. |
| We've now Added Support For Retries. | You can now retry failed requests. |
| Click here for more info. | See [Configure retries](#). |

From influxdata/docs-skills, MIT.

More from influxdata/docs-skills