writing-style

Writing style

Technical prose in this repo follows the Google developer documentation style guide, condensed below. The goal is plain, direct writing that does not read as AI-generated.

Exception: pages under mintlify/legal/ are verbatim text provided by Legal. Do not restyle them; change them only as instructed, word for word.

Sentences

• Active voice. Name who does the action: "Grid retries the payout", not

"the payout is retried". Passive is fine when the actor is irrelevant ("the quote expires after 30 seconds").

• Second person for instructions: "you", not "we" or "the user".
• Present tense: "the webhook fires when the transaction settles", not

"will fire".

• Condition before instruction: "To receive status updates, register a

webhook", not "Register a webhook if you want status updates". Same for links: "For supported currencies, see X", not "See X for supported currencies".

• One idea per sentence. Short sentences, but complete ones. No fragments

for effect.

• Say it once and stop. Cut any sentence that restates the previous one.

Words

• Plain words over jargon and buzzwords. Name the actual endpoint, field,

status, error code, or currency, not "the system" or "the workflow".

• Never "simply", "just", "easy", or "quickly" in instructions.
• No placeholder phrases: "please note", "at this time", "it's worth

noting", "keep in mind".

• No figurative language, metaphors, or pop-culture references.
• Introduce a term once, then use it consistently. Don't rotate synonyms

for variety.

Formatting

• Sentence case for titles and headings.
• Numbered lists only for ordered steps; bullets for everything else. One

concrete behavior per bullet.

• Serial comma.
• Code font for endpoints, fields, values, and commands. Bold for UI

elements.

• Link text describes the destination ("see the quote lifecycle"), never

"click here" or a bare "here".

• Unambiguous dates (2026-08-19 or "August 19, 2026").
• No exclamation marks.
• No em-dashes. Use commas, periods, parentheses, or restructure the

sentence.

Content

• Write for a reader who was not in the working session. No shorthand or

codenames invented while drafting; spell out what happens.

• Don't document unreleased or future behavior. Describe only what the API

does today.

• Paste real request/response bodies and error payloads in code blocks;

never paraphrase what the API returns.

• State trade-offs directly: "chose X over Y because Z". No hedging, no

selling.

• Structure follows the content: add a heading or bullet list only when

there are genuinely multiple items.

• Lead with the conclusion or the change; background after.
• No summary or conclusion sections that restate the page.

PR descriptions and review comments

• PR descriptions say what changed and why, in complete sentences, one

behavior per bullet. The test plan states what was actually run.

• Review comments open with the point ("nit:", "question:") and quote the

specific line or output. One finding per comment. Frame a suggestion as a question when the author may know something you don't.

De-AI pass (run last, on every draft)

• No AI jargon or grand framing: "first-class", "end-to-end", "robust",

"seamless", "leverage", "holistic", "comprehensive", "battle-tested".

• No punchy fragments for effect: "No more X.", "The result? Y.", "Simple."
• No "It's not X, it's Y" constructions, rhetorical questions, or triadic

flourishes ("faster, safer, simpler").

• If a sentence could open a product blog post, rewrite it as a statement

of fact.