​

Style guide

​

How to set it

style_guide: |
  Write like Stripe's API docs: short sentences, second person ("you").
  One runnable code example per endpoint.
  Use tables for parameters with columns: Name, Type, Required, Description.
  Never use marketing adjectives ("powerful", "seamless").
  British spelling.

@docagent style "Short sentences. Tables for params. A code example per endpoint. No marketing language."

​

What to put in it

• Voice & person — “second person”, “imperative”, “no first-person plural”.
• Sentence length & tone — “short declarative sentences”, “no marketing language”.
• Structure — “every endpoint gets: summary, params table, example, response”.
• Formatting — “use tables for parameters”, “fenced code blocks with language tags”.
• Terminology — “call it a workspace, never a project”.
• Spelling/locale — “US English”, “Oxford comma”.
• Examples — “prefer curl examples”, “use realistic values, not foo/bar”.

​

Good vs. vague

​

What the style guide does not do

• It does not make ZAR invent content. ZAR still only edits docs to match real code changes; the style guide shapes how it writes, not whether it writes.
• It does not change which files ZAR touches — that’s trigger modes and significance.
• It does not override language detection. ZAR writes each doc in the language it’s already in (see MDX & multilingual); the style guide tunes wording within that language.

​

Tips

• Keep it to a handful of strong rules. A wall of text dilutes the signal.
• Mirror the conventions already in your best docs page, so new edits blend in.
• Iterate: open a PR, read ZAR’s edit, and add a rule for anything that felt off.

​

Next steps

• .zar.yml reference — the style_guide key.
• Commands — set the style from a PR comment.
• PR feedback — see the style applied in a real suggestion.