Writing style

mintlify/legal/

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.