---
name: plain-prose
description: Applies the Google developer documentation style guide to prose:
  plain, checkable technical English with no aphorisms, buzzwords, or filler.
  Use when asked for Google style or "the style guide", and when writing or
  reworking technical prose: a summary or status report, a findings list, a
  README, design doc, spec, or runbook, a commit body, a code comment,
  release notes, PR or issue text, or a draft written for the user. Also use
  when asked to tighten, proofread, or de-slop existing prose, or when asked
  why a sentence reads as AI-written. Not a global default: for informal or
  non-technical writing, follow the user's own register instead.
---

# Prose conventions

Source: the Google developer documentation style guide. Each file under
`references/` names the guide pages it extracts, so a disputed rule is
settled there, by citation. Rules marked "extension" are house additions,
not the guide's. Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Register

The guide asks for "conversational, friendly, and respectful", like "a
knowledgeable friend". Extension: aim instead at a senior engineer writing
to a competent colleague, specific and unhurried, nothing staged for effect.

| Too informal | Right | Too formal |
|---|---|---|
| Dude! This API is totally awesome! | This API lets you collect data about what your users like. | The API documented by this page may enable the acquisition of information pertaining to user preferences. |
| Nailed it, tests are green | All 34 tests pass. Two were already failing on `main`, so I left them. | Test execution completed with satisfactory results. |

Avoid buzzwords, figurative language, pop-culture references, internet
slang, and exclamation marks. Never call anything simple or easy. Extensions
in the same spirit: no emoji, and no praise as preamble ("Great question",
"You're absolutely right").

## Don't compress a finding into an aphorism (extension)

A technical summary needs statements the reader can test against the code.

| Aphorism | Claim |
|---|---|
| Data flows in one direction | Reducers are the only place state changes |
| Tests are the specification | The test names describe the intended behavior |
| Errors are values, not events | Failures are returned, not thrown |
| Boundaries carry the contract | The boundary validates input; nothing below it does |

If a reader can't disagree with the sentence, it carries no information. This
covers headings, bullet summaries, closing lines, and titles. A heading labels
the section it opens.

## Reporting your own work (extension)

First person for what you did, past tense; present tense for the behavior
that resulted: "I changed both call sites. The retry count is read once."
Lead with what is true now, then what changed, then what you left undone and
why. If you don't name a gap, the reader assumes there isn't one.

## Sentences

- Active voice, and name who acts.
- Present tense. Reserve `will` for something that genuinely happens later.
- No em dashes (extension). Use a comma, a colon, parentheses, or two sentences.
- Conditions before instructions: "To delete the document, click Delete."
- Second person. Address the reader as "you", not "the user".
- Under 26 words. Cut `in order to` to `to`, `make use of` to `use`,
  `a number of` to `some`.
- No anthropomorphism. Software doesn't want, think, know, or try.
- Put `only` next to what it limits: "Request only one token."
- Keep `then`, `that`, `of`. Two characters, and they save a re-read.
- No ambiguous pronouns: "the text doesn't change", not "it doesn't change".
- No directional references. "The preceding section" survives a re-layout,
  "above" doesn't.
- Two nouns of modifier stacking, maximum, unless three is the established
  name of the thing (payment retry queue).

## Paragraphs and order

Most important information first, in the paragraph and in the reply. One idea
per paragraph. Past five or six sentences, look for the second idea. A
one-sentence paragraph is fine.

## References

Read the file for the topic at hand, not all eight.

| Topic | File |
|---|---|
| Voice, tense, person, pronouns, agreement | `references/grammar.md` |
| Capitalization, punctuation, numbers, dates, units | `references/mechanics.md` |
| Words to avoid, jargon, inclusive language, the slop list | `references/word-list.md` |
| Headings, lists, procedures, notices, tables, links | `references/documents.md` |
| Code font, code samples, command syntax, placeholders | `references/code.md` |
| Claims, must/should/can, superlatives, verified versus assumed | `references/claims.md` |
| Product names, trademarks, filenames | `references/names.md` |
| Markdown versus HTML, semantic tagging | `references/markup.md` |

## Before you send

- Any sentence a reader couldn't disagree with? Rewrite it as the claim it
  replaced.
- Outcome in the first sentence?
- Every heading a plain label, in sentence case?
- Any word from the slop list, any `just`, `simply`, `leverage`, `robust`,
  `seamless`?
- Passive voice where the actor matters?
- Any superlative or guarantee you can't support?
- Anything asserted that you didn't actually check?
- Anything you skipped that you haven't admitted?