General Style Guide Example
A practical reference for producing technical content that serves developers. Leverages Google, Microsoft, Apple, Oxford, and Stripe style guides with project-specific conventions.
Technical Style Guide
14 sections
Documentation as Product
Treat docs as a first-class product.
Documentation drives adoption. Great docs compress time-to-first-success from weeks to minutes. Every page should feel like an application.
Dual-Audience Design
Write for humans first, structure for machines always.
Modern documentation serves developers reading docs and AI systems retrieving context. Optimize for both.
Progressive Disclosure
Show users what they need when they need it.
Layer information: essential → detailed → advanced. Limit to 2 levels maximum. More creates confusion.
Jobs-to-be-Done
Document tasks, not features.
Ask: "What job is the developer hiring this documentation to do?" Focus on functional outcomes over technical specifications.
Content should meet style guidelines, include sufficient examples, have descriptive commit messages, and provide evidence of compatibility. High-quality peer review is essential.
Small, regularly submitted contributions. Larger submissions are split into self-contained, individually reviewable units.
Contributors take responsibility for maintaining their content over time.
Warm & Relaxed
Natural, less formal, grounded in real everyday conversations.
Do
- ✓Write like you speak
- ✓Use contractions naturally
- ✓Be conversational
Don't
- ✗Sound robotic or bureaucratic
- ✗Use corporate jargon
- ✗Be overly casual
Crisp & Clear
To the point. Write for scanning first, reading second.
Do
- ✓Get to the point fast
- ✓Lead with what matters
- ✓Make it simple
Don't
- ✗Bury the lede
- ✗Use flowery language
- ✗Over-explain
Ready to Help
Show readers you are on their side. Anticipate their needs.
Do
- ✓Offer information at the right time
- ✓Anticipate questions
- ✓Provide escape hatches
Don't
- ✗Assume readers should figure it out
- ✗Hide critical information
- ✗Make users feel stupid
Point of View
Default choice. Address the reader directly with "you".
"You can configure..." not "Users can configure..."
Use "we" for tutorials where you guide a shared journey.
"Let us build a simple API..."
Never use "I". It obscures the reader's journey.
Avoid: "I recommend..." Use: "Consider..."
Use for describing system behavior objectively.
"The API returns..." not "We return..."
Tone by Context
| Context | Tone | Goal |
|---|---|---|
| Quickstart | Energetic, encouraging | Get to first success fast |
| Conceptual | Clear, patient, thorough | Build understanding |
| Reference | Precise, scannable, neutral | Answer specific questions |
| Troubleshooting | Empathetic, solution-focused | Unblock without blame |
Avoid Weasel Words
Avoid: easily, simply, just, quickly, obviously
What's simple to you may not be simple to the reader. These words dismiss difficulty.
→ Remove entirely or replace with specific guidance.
Temporal Precision
Avoid: "when" (ambiguous), "since" (temporal vs causal)
"When" can mean "if" or "at the time." "Since" can mean "because" or "from that time."
→ Use "after" for time, "because" for causation, "if" for conditions.
Remove Filler
Avoid: in order to, as well as, and then, basically, actually
These add words without adding meaning.
→ "to" not "in order to", "and" not "as well as", remove "then" after "and".
Expand Abbreviations
Avoid: e.g., i.e., etc., vs.
Abbreviations are often misused and harder to translate.
→ "for example", "that is", rephrase to be specific, "compared with".
Sentence Guidelines
- •One idea per sentence. Break compound sentences.
- •Lead with the action or outcome.
- •Use active voice: "The function returns..." not "A value is returned..."
- •Keep sentences under 25 words when possible.
- •Avoid double negatives and nested conditionals.
- •Write for a global audience - avoid idioms and cultural references.
Developers have ~47 seconds of screen attention and working memory limited to ~4 items. Design for interruption recovery and scanning.
4-Item Rule
Limit concepts per section to 4 or fewer. Working memory research shows this is the true limit.
→ Break long lists into chunked groups. Each subsection should have a singular focus.
Scan-First Design
Developers scan before they read. 41% cite insufficient documentation as a major time loss.
→ Front-load important information. Make every paragraph's first sentence carry the key point.
Interruption Recovery
Focus recovery after interruption takes ~25 minutes. Developers constantly context-switch.
→ Use clear section headings as bookmarks. Each section should be self-contained.
EAS Framework
Eliminate → Automate → Simplify. Before adding content, ask if it should exist at all.
→ Eliminate unnecessary content. Automate repetitive explanations. Simplify what remains.
Types of Cognitive Load
Intrinsic
Inherent complexity of the concept itself
Manage through progressive disclosure
Extraneous
Complexity from poor presentation
Eliminate through better formatting and clearer language
Germane
Productive learning effort
Encourage through examples and hands-on exercises
Documentation must serve both human readers and AI retrieval systems.
Semantic Headings
Use descriptive H1-H6 headings that capture purpose. AI retrieval depends on heading quality.
✓ "Configure authentication with OAuth 2.0" ✗ "Configuration" or "Step 3"
Section Summaries
Add 1-2 sentence summary after major headings. Increases semantic coverage for embedding search.
After "## Error Handling" add: "This section covers how to catch, log, and recover from errors."
Flat Hierarchy
Prefer flat lists over deeply nested structures. LLMs process flat hierarchies more coherently.
✓ Use 2 levels of bullets max ✗ Avoid 4+ levels of nesting
Canonical Phrasing
Same concept = same term. Avoid synonyms for technical terms.
✓ Always "endpoint" not sometimes "route" or "URL"
Explicit Context
Define abbreviations explicitly. Assume no prior context.
✓ "The CLI (Command Line Interface) provides..."
Chunking for RAG
Chunking is the most important factor for RAG performance.
| Strategy | Tokens | Use Case |
|---|---|---|
| Semantic Chunking | 256-512 | Knowledge bases, conceptual docs |
| Recursive Chunking | 512-1024 | Structured reports, long-form content |
| Language-Specific | Varies | Code documentation, API references |
💡 Semantic chunking improves accuracy by ~70% by grouping sentences by meaning rather than arbitrary token counts.
Frontmatter Metadata
Required
title, description, keywords
Recommended
topics, audience, complexity, sdk, updated
Optional
ai-summary, deprecated, featured
Quickstart
Energetic, encouragingGet to first success in <5 minutes
Prerequisites → 3-5 steps → Working result → Next steps
Tutorial
Patient, educational, use "we"Teach a concept through building
Learning goal → Prerequisites → Step-by-step build → Result
Conceptual
Clear, thorough, use analogiesBuild mental models and understanding
What it is → Why it matters → How it works → When to use it
Reference
Precise, neutral, comprehensiveAnswer specific questions quickly
Scannable format → Parameters → Return values → Examples
Troubleshooting
Empathetic, solution-focusedUnblock users who are stuck
Symptom → Cause → Solution → Prevention
Heading Hierarchy
- •H1: Page title (one per page)
- •H2: Major sections
- •H3: Subsections within H2
- •H4: Use sparingly for deep subsections
- •Never skip heading levels (H2 → H4)
- •Headings should be scannable - capture the section's purpose
Navigation Patterns
Three-Column Layout
Left: Navigation. Center: Content. Right: Code examples.
API documentation
Progressive Layers
Getting Started → Guides → API Reference → Architecture
Framework documentation
Search-First
Prominent search with good taxonomy and crosslinks
Large documentation sites
Code Blocks
- •Always specify the language for syntax highlighting
- •Provide complete, runnable examples - no pseudo-code for tutorials
- •Test all code before publishing
- •Use 2-space indentation (or language convention)
- •Wrap lines at 80 characters for readability
- •Include comments explaining non-obvious logic
- •Show expected output where helpful
Inline Code
- •Use code font for: filenames, class names, method names, variables, CLI commands, HTTP methods, status codes
- •Don't use code font for: product names, company names, general technical terms
- •First mention of a function should include parentheses: getValue()
Placeholders: UPPER_SNAKE_CASE for placeholders
Always explain placeholders on first use
YOUR_API_KEY – Replace with your API key from the dashboard
PROJECT_ID – Your project identifier
AI-Friendly Comments
- ✓Write comments that explain "why" not "what" - the code shows the what
- ✓Include context about constraints and edge cases
- ✓Document expected inputs/outputs clearly
- ✓Use consistent patterns that AI can learn from
Paragraphs
- •One idea per paragraph
- •First sentence carries the key point
- •Keep paragraphs to 3-5 sentences
- •Use transition words sparingly but effectively
Lists
Use for 3+ items; use prose for 2 or fewer
Use only when order matters
Prefer over tables for simple key-value pairs
Tables
- Use tables for structured comparisons
- Keep tables simple - if it needs >5 columns, reconsider
- Include header row
- Left-align text, right-align numbers
Callouts
Additional context that's helpful
Best practices, shortcuts, pro tips
Potential problems that won't cause data loss
Actions that could cause data loss or security issues
Use callouts sparingly. If everything is important, nothing is. Max 2 per page section.
Images
- •Include alt text for all images (accessibility and AI context)
- •Use screenshots to show UI, diagrams to show architecture
- •Annotate screenshots to highlight relevant areas
- •Keep images under 1MB; optimize for web
Sentence case for headings and titles
"Configure authentication settings" not "Configure Authentication Settings"
Less formal, easier to read, consistent across translations
File Naming: Use kebab-case for URLs and filenames
getting-started.md, api-reference.md, error-handling.md
URL-friendly, consistent, works across operating systems
Credentials & Keys
- •Never show real API keys, passwords, or secrets in examples
- •Use clearly fake placeholder values: YOUR_API_KEY, sk_test_xxx
- •Document secure storage practices alongside credential usage
- •Include rotation and revocation guidance
Code Examples
- •Examples should follow security best practices by default
- •Validate inputs in all examples - don't teach insecure patterns
- •Use HTTPS in all URL examples
- •Show error handling, not just happy path
Blockchain & Financial
- •Always demonstrate on testnet first
- •Emphasize key management best practices
- •Include "no liability" language for funds and value transfer
- •Add disclaimers for production use
Disclaimers
When: Include disclaimers for: production use, financial data, security-sensitive operations
How: Use callouts (Warning/Caution) positioned before the dangerous action
Technical content makes claims. Those claims need support.
Premises
Clear, verifiable statements that form the foundation
Evidence
Empirical data (benchmarks, research) or theoretical justification (spec, standard)
Conclusions
Results that follow logically from premises and evidence
Logical Connectives
Fallacies to Avoid
WCAG Essentials
- •All images have descriptive alt text
- •Color is not the only indicator of meaning
- •Links are descriptive ("Read the configuration guide" not "Click here")
- •Content is navigable by keyboard
- •Sufficient color contrast (4.5:1 for normal text)
Plain Language
- •Write at an 8th-grade reading level when possible
- •Prefer common words over technical jargon
- •Define technical terms on first use
- •Use short sentences and active voice
Translation-Ready
- •Plan for text expansion (German is ~15% longer than English)
- •Avoid idioms, puns, and culturally-specific references
- •Don't hardcode strings - use localization files
- •Use ISO date formats (YYYY-MM-DD) or spell out months
Self-Review
- ☐Read aloud - does it sound natural?
- ☐Check against style guide
- ☐Test all code examples
- ☐Verify links work
- ☐Run accessibility check
Peer Review
- ☐Is it accurate and complete?
- ☐Is it clear to someone unfamiliar with the topic?
- ☐Does it follow style guidelines?
- ☐Are there opportunities to simplify?
Technical Review
- ☐Are technical claims correct?
- ☐Do code examples work?
- ☐Are edge cases covered?
- ☐Does it reflect current API/product state?
Maintenance Cadence
| Frequency | Action |
|---|---|
| Every Release | Update version references, API changes, new features |
| Monthly | Check analytics for underperforming pages; review user feedback |
| Quarterly | Content audit for accuracy; archive deprecated content |
| Annually | Full information architecture review; style guide update |
Feedback Loop
- •Monitor support tickets for documentation gaps
- •Track search queries with no results
- •Review page analytics (bounce rate, time on page, scroll depth)
- •Collect explicit feedback (ratings, comments)
Deprecation: Don't delete - redirect or archive
Mark as deprecated with banner → Link to replacement content → Set redirect from old URL → Remove from navigation after 2 release cycles → Maintain URL for 1 year minimum