Mechanics are the small, consistent choices that let a person scan copy without snagging: how we capitalise, write numbers, and punctuate. This page collects the conventions we apply everywhere. The writing craft that shapes the words themselves — concise, conversational, clear — lives in Writing.
Capitalisation and numbers
- Sentence case everywhere — headings, buttons, labels (CNT-12). Capitalise the first word and proper nouns only.
- Numerals for counts ("8 projects", not "eight"). Separate a number and its unit with a space.
Headings
- Statement headings, not question headings. "Verify the installation", not "Did it work?" — a heading says what the section does or covers.
- "And", not "&", in headings and titles, unless the ampersand is part of a proper name.
Punctuation and abbreviations
- Use real punctuation: an em dash, never a hyphen standing in for one.
- No Latin abbreviations in prose: "for example", not "e.g."; "that is", not "i.e."; "and so on", not "etc.".
- Spell out a term before abbreviating it, and abbreviate only terms readers meet again ("merge request (MR)" earns its shorthand; a one-off doesn't).