DOMAIN:CONTENT — STYLE GUIDES¶
OWNER: jouke, dinand
ALSO_USED_BY: benjamin, joost, margot (Client Communications)
UPDATED: 2026-03-24
STYLE_GUIDES:GOOGLE_DEVELOPER_DOCS¶
STANDARD: Google Developer Documentation Style Guide
SOURCE: https://developers.google.com/style
Key Rules¶
RULE: use second person ("you") — never first person ("we") in instructions
RULE: use active voice — "Click Save" not "The Save button should be clicked"
RULE: use present tense — "This method returns" not "This method will return"
RULE: use sentence case for headings — "Create a new project" not "Create a New Project"
RULE: use serial (Oxford) comma — "red, green, and blue"
RULE: place conditions before instructions — "To save your work, click Save" not "Click Save to save your work"
RULE: use standard American English spelling
RULE: use descriptive link text — "see the installation guide" not "click here"
RULE: use numbered lists for procedures, bullet lists for everything else
RULE: format code-related text in code font (monospace)
RULE: bold UI element names — Save, Settings
RULE: use unambiguous date formats — "March 24, 2026" or "2026-03-24" never "3/24/26"
RULE: provide alt text for all images
Word Preferences¶
| Avoid | Use Instead |
|---|---|
| "application" | "app" (for end-user software) |
| "terminate" | "stop" or "end" |
| "utilize" | "use" |
| "in order to" | "to" |
| "leverage" | "use" |
| "please" | omit (not conversational for docs) |
| "easy" / "simple" | omit (subjective, may not be true for reader) |
| "obviously" | omit (if obvious, why document it?) |
| "basically" | omit (filler) |
STYLE_GUIDES:MICROSOFT_WRITING¶
STANDARD: Microsoft Writing Style Guide
SOURCE: https://learn.microsoft.com/en-us/style-guide/welcome
Key Rules¶
RULE: warm, relaxed, crisp, clear — like talking to a person one-on-one
RULE: focus on the reader's intent — what task are they trying to do?
RULE: use simple sentences — one idea per sentence
RULE: use sentence case for headings and titles
RULE: use second person ("you") to address the reader directly
RULE: use plural pronouns ("they/their") for generic references
RULE: include small words ("a", "the", "that") — critical for machine translation
RULE: don't break up steps with commentary — put extra info in code comments
RULE: reference docs = encyclopedia of all programming elements
RULE: code examples = show how to use those elements
RULE: bold for UI element names in instructions
RULE: consistent sentence construction — subject near beginning
Microsoft vs. Google Differences¶
| Aspect | Microsoft | |
|---|---|---|
| Tone | Conversational, direct | Warm, friendly, supportive |
| Headings | Sentence case (strict) | Sentence case (strict) |
| Serial comma | Always | Always |
| Contractions | OK | Encouraged |
| "Please" | Avoid | Avoid |
| Person | 2nd person | 2nd person |
NOTE: Google and Microsoft guides align on >90% of rules. Key difference is tone — Google is more direct, Microsoft is warmer.
STYLE_GUIDES:APPLE¶
STANDARD: Apple Human Interface Guidelines — Writing
SOURCE: https://developer.apple.com/design/human-interface-guidelines/writing
STANDARD: Apple Style Guide
SOURCE: https://help.apple.com/pdf/applestyleguide/en_US/apple-style-guide.pdf
Key Rules¶
RULE: words are part of the user experience — treat copy as a design element
RULE: choose title case OR sentence case — be consistent throughout the app
RULE: title case is more formal, sentence case is more casual — choose per brand
RULE: pick first person OR second person — "My Favorites" or "Your Favorites", never both
RULE: be consistent with flow labels — "Continue" or "Next", not both
RULE: use "app" for iOS/iPadOS/watchOS/visionOS software
RULE: use "turn on/off" not "activate/deactivate" or "enable/disable"
RULE: "The setup assistant appears" not "is displayed" — things appear, not "are displayed"
RULE: avoid jargon — use concise, descriptive language
Apple Terminology Preferences¶
| Avoid | Use Instead |
|---|---|
| "activate/deactivate" | "turn on/turn off" |
| "is displayed" | "appears" |
| "enable/disable" | "turn on/turn off" |
| "application" | "app" |
| "click" (on touch devices) | "tap" |
| "swipe" (for specific gesture) | "swipe" (Apple approves this term) |
| "grayed out" | "dimmed" |
iOS-Specific Copy Rules¶
RULE: iOS uses "Settings" (capital S) for the system app
RULE: use "Home Screen" not "home screen" (Apple capitalizes it)
RULE: use "sign in" not "log in" (Apple preference)
RULE: system alerts use two-button pattern — one action verb, one "Cancel"
RULE: sheet titles are nouns or noun phrases, not questions
STYLE_GUIDES:PROJECT_SPECIFIC¶
How to Create a Client Style Guide¶
RULE: every client project gets a style guide before content work begins
RULE: content leads (jouke, dinand) create and own the guide
RULE: technical writers (benjamin, joost) contribute developer docs section
Style Guide Template¶
CLIENT STYLE GUIDE TEMPLATE:
1. VOICE & TONE
- Brand personality (3-5 adjectives from client)
- Voice matrix (see UX_WRITING:TONE_OF_VOICE)
- "We are / We are not" pairs
2. GRAMMAR & MECHANICS
- Heading case: title case or sentence case
- Serial comma: yes or no
- Person: first or second
- Contractions: yes or no
- Abbreviations: expand on first use or not
- Base style guide: Google / Microsoft / Apple (pick one as foundation)
3. TERMINOLOGY
- Product-specific word list (what to call features)
- Banned terms (competitor names, deprecated features)
- Glossary of domain terms
4. UI COPY PATTERNS
- Button labels (verb + object format)
- Error messages (3-part template)
- Empty states (illustration + explanation + CTA)
- Notification patterns per channel
5. TECHNICAL DOCS (if applicable)
- API reference format
- Code sample language priority
- Changelog format
6. I18N RULES
- Target languages
- Translation workflow
- Locale-specific exceptions
7. PLATFORM-SPECIFIC RULES
- Web (follows base guide)
- iOS (follows Apple HIG additions)
- Android (follows Material Design additions)
RULE: start from closest existing guide (Google for developer products, Apple for iOS apps)
RULE: add project-specific overrides only — don't rewrite the base guide
RULE: word list is living document — add terms as they emerge
RULE: review style guide quarterly with client
ANTI_PATTERN: writing a 50-page style guide nobody reads
FIX: one-page summary + detailed reference. Most people only need the summary.
ANTI_PATTERN: no style guide at all — each developer writes differently
FIX: minimum viable style guide = voice + word list + UI patterns
TOOL: vale — automated prose linting against style guide rules
RUN: vale --config=.vale.ini docs/
NOTE: vale supports Google, Microsoft, and custom style packages
RUN: vale ls-config to check active style rules