Style cheat sheet
See the full style guide.
| Rule | Do | Don't |
|---|---|---|
| Content type | One page, one job (tutorial / how-to / reference / explanation) | Tutorials with inline "alternatively…" branches |
| Voice | Second person, active, present | "The script should be run" |
| Person | "You can…" framing | "X allows users to…" |
| Headings | Sentence case, descriptive, no trailing colon | "Overview", "Configuration:" |
| Comma | Oxford comma, always | — |
| Spelling | American | organise, behaviour |
| UI/files in steps | Bold | "quotes" or italics |
| Code, params, paths | code font | plain prose |
| Lists of facts | Tables | paragraph-form parameter lists |
| Numbered steps | 1. for every item in source | hand-numbered 1. 2. 3. |
| Numbers | Spell out one–nine; numerals 10+ | "10,000" spelled out |
| Admonitions | note / warning / tip, sparingly, never a required step | stacked boxes |
| Em dashes | Avoid; shorter sentences | — |
| Filler | Cut "simply", "just", "easy", "please" | — |
| Internal links | Relative, with .md, descriptive text | "click here", bare URLs |
| Terminology | OAuth · Kroger API · kroger-api · access token · rate limit · ZIP code | Oauth · Kroger api · ratelimit · zipcode |
| Objectives (tutorials) | 3–4, action verbs, measurable | "understand X" |
| Knowledge checks | Scenario-shaped, consequence-narrating feedback, one objective each | trivia recall, "Incorrect. Try again." |
| Sections | Self-contained, first sentence says what it is | "as mentioned above" |
| Code fences | Complete, runnable, language-tagged | fragments with elided context |