documentation-standards

# Documentation Standards ## Overview Comprehensive documentation standards based on research from Google, Microsoft, GitLab, Red Hat style guides, and 60+ additional sources. Provides templates, best practices, and anti-pattern detection for AI agents writing documentation. --- ## 15 Best Practices (Ranked by Consensus) ### UNANIMOUS (100% Agreement) #### 1. Use Active Voice and Present Tense **Why**: Reduces cognitive load 20-30%, shortens sentences 15-25% **Implementation**: ```markdown BAD (passive): The request is processed by the server. GOOD (active): The server processes the request. BAD (future): The program will save your file. GOOD (present): The program saves your file. ``` **Validation**: Check for "is/are/was/were + past participle" patterns --- #### 2. Start with 5-Minute Quick Start **Why**: 70% of visitors are first-time users, time-to-first-success critical **Implementation**: ```markdown ## Quick Start ```bash npm install my-tool npx my-tool init npx my-tool start ``` Visit http://localhost:3000 That's it! ``` **Validation**: Can a new user succeed in under 5 minutes with zero context? --- #### 3. Use Progressive Disclosure (Three-Tier Structure) **Why**: Accommodates all skill levels, reduces overwhelm **Implementation**: ``` Tier 1: Quick Start (2-5 min) -> Copy-paste code, immediate success, no explanations Tier 2: Tutorial (15-30 min) -> Step-by-step with explanations, build one feature Tier 3: Reference (lookup) -> Complete API docs, searchable, advanced patterns ``` --- #### 4. Use Second Person ("You") **Why**: Increases engagement, reduces word count 15-25% **Implementation**: ```markdown BAD: The user should configure the settings. GOOD: Configure the settings. BAD: One can install the plugin by... GOOD: Install the plugin by... ``` --- #### 5. Keep Sentences Short (Rule S2) **Why**: Long sentences cost comprehension. Rule S2 sets the numbers: average 15-20 words, at most one 26-40 word sentence per paragraph, none over 40. **Implementation**: ```markdown BAD (42 words): The configuration file, which should be located in the root directory of your project and named .claude, contains all the settings that are required for the plugin system to function correctly and load the appropriate agents. GOOD (18 words): Place the `.claude` configuration file in your project root. It contains settings for the plugin system and agents. ``` --- #### 6. Use Lists and Tables for Comparison **Why**: 70% faster comprehension vs paragraphs **Implementation**: ```markdown ## Prerequisites Before starting, you need: - [ ] Node.js 18+ installed - [ ] Git access to GitHub - [ ] API token configured ## Tool Comparison | Tool | Best For | Stars | Learning Curve | |------|----------|-------|----------------| | Docusaurus | React | 55k+ | Medium | | VitePress | Vue | 12k+ | Low | ``` --- ### STRONG (67%+ Agreement) #### 7. Use Language-Specific Documentation Tools **Why**: Deep language integration, automatic type inference **Decision Matrix**: ``` Language -> Tool: - TypeScript -> TSDoc comments + TypeDoc generator - Python -> Google/NumPy docstrings + Sphinx - Rust -> /// comments + rustdoc - Go -> Plain comments + godoc - Java -> Javadoc ``` --- #### 8. Follow Diataxis Framework **Why**: Clear taxonomy reduces confusion **Four Types**: | Type | Purpose | Length | When to Use | |------|---------|--------|-------------| | Tutorial | Teach by doing | 15-60 min | "I'm new, show me" | | How-To | Solve problem | 5-15 min | "I need to do X" | | Reference | Describe what exists | As needed | "What parameters?" | | Explanation | Clarify concepts | 5-30 min | "Why does this work?" | --- #### 9. Show Code Examples with Expected Output **Why**: Users know what success looks like **Implementation**: ```markdown ### Example: Fetching User Data **Code:** ```typescript const user = await api.getUserById('user-123'); console.log(user.name, user.email); ``` **Expected Output:** ``` John Doe john@example.com ``` **Error Case:** ```typescript const user = await api.getUserById('invalid-id'); // Throws: NotFoundError: User with ID 'invalid-id' not found ``` ``` --- #### 10. Provide Troubleshooting Section **Why**: 50%+ of support questions are error-related **Template**: ```markdown ## Troubleshooting ### Issue: Command not found **Symptom**: `/implement` returns "command not found" **Cause**: Plugin not enabled **Solution**: 1. Check `.claude/settings.json` 2. Run `/plugin reload` 3. Restart if needed **Prevention**: Verify with `/plugin list` ``` --- #### 11. Organize by Task ("How do I...") **Why**: Users think in terms of goals, not architecture **Implementation**: ```markdown ## Guides ### How-To Guides (Task-Oriented) - [How to deploy to production](deploy.md) - [How to add authentication](auth.md) - [How to handle file uploads](uploads.md) ``` --- #### 12. Add Prerequisites Checklist **Why**: Eliminates invisible barriers for beginners **Template**: ```markdown ## Prerequisites Before starting, ensure you have: - [ ] Node.js 18+ installed ([Download](https://nodejs.org)) - [ ] Basic JavaScript knowledge - [ ] Text editor (VS Code recommended) ``` --- ### AI-SPECIFIC #### 13. Verify Examples Actually Work **Why**: Prevents hallucination and outdated examples **Process**: 1. Read function implementation 2. Extract actual parameters and return type 3. Test example code 4. Document actual output --- #### 14. Ground Documentation in Source Code **Why**: Prevents documenting non-existent features **Process**: 1. Read source code FIRST 2. Only document features that exist 3. Use actual type signatures 4. If uncertain, qualify with "typically", "generally" --- #### 15. Add Version Tracking **Why**: Users need to know if docs apply to their version **Template**: ```markdown --- **Version**: v2.0.0 **Last Updated**: 2026-01-09 **Compatible With**: Claude Code 1.5+, TypeScript 5.0+ --- > **DEPRECATED**: This approach works but superseded by [New Approach](link) ``` --- ## Anti-Slop Writing Rules These rules eliminate AI-detectable writing patterns and enforce professional technical writing standards. dev:docs MUST apply these rules in write and fix modes, and check for violations in analyze mode. ### Rule S1: Banned Words and Phrases NEVER use these words or phrases. Each tier has escalating severity. **CRITICAL — instant disqualifier (AI generation artifacts):** - "As an AI", "As a language model", "I'd be happy to", "Certainly!", "Absolutely!", "Great question!", "I hope this helps", "Feel free to ask", "Let me explain", "Allow me to clarify" - "In today's [anything] world", "In an increasingly [adj]", "In the realm of", "At the heart of", "The weight of [X]" **HIGH — marketing superlatives and difficulty dismissers:** - amazing, revolutionary, powerful, robust, seamlessly, effortlessly, incredible, world-class, cutting-edge, state-of-the-art, next-generation, innovative, game-changing, industry-leading, best-in-class - simply, easy, just, obviously, of course, clearly, trivially, straightforward, quick **MEDIUM — corporate jargon and filler:** - leverage, utilize, streamline, facilitate, empower, unlock, accelerate, transform, drive (metaphorical), deliver value, synergy/synergize, actioning, comprehensive (unless you enumerate what it covers) - "it is worth noting that", "it is important to note", "please note that", "as mentioned above", "as stated earlier", "due to the fact that" (use "because"), "in the event that" (use "if"), "in order to" (use "to"), "might potentially", "could potentially", "may or may not" **STRUCTURAL OVERHEAD — throat-clearing and meta-commentary:** - "In this section, we will discuss...", "This document covers...", "Now that we have...", "As you can see...", "This section explains...", "Let's explore...", "Let's take a look at...", "Let's dive into..." - Never begin a section with a sentence that describes the section. Start with the first piece of actual content. **HEDGING CASCADES — qualify-then-qualify patterns:** - "It's important to note that... depending on your specific use case" - "While this may vary... it generally tends to..." - "...depending on your particular requirements/needs/situation" - Maximum 2 hedge phrases per 1000 words. Technical docs should be authoritative. - Counted hedge phrases: "may vary", "might", "could potentially", "may or may not", "generally", "typically", "tends to", "in most cases", "depending on your", "it is important to note", "it's important to note", "arguably", "somewhat", "relatively" **Counting is a script's job.** `scripts/doc-metrics.ts` counts every term in this rule, and the sentence, heading, code-ratio and link metrics in the rules below, with line numbers: ```bash bun ${CLAUDE_PLUGIN_ROOT}/skills/documentation-standards/scripts/doc-metrics.ts <file.md> ``` Its term lists are this rule's lists; its test fails when one has a term this rule lacks. --- ### Rule S2: Sentence Length and Rhythm Vary sentence lengths for natural rhythm. Monotonous sentence length signals AI generation. **Targets:** - Average sentence length: 15-20 words - Short sentences (≤10 words) for key points and transitions - Medium sentences (11-25 words) for explanations - Long sentences (26-40 words) allowed for complex technical explanations, maximum 1 per paragraph - NEVER exceed 40 words in a single sentence **Anti-monotony rule**: No more than 3 consecutive sentences within ±5 words of each other. **Transitions**: Words like "however", "therefore", "for example" help readers connect ideas. Use them — but don't open more than 40% of paragraphs with an explicit transition word. --- ### Rule S3: Structural Variety (Anti-AI-Pattern) AI-generated text has detectable patterns. Avoid these: **Paragraph variety**: Don't lock every paragraph into topic-sentence → supports → conclusion. Start some paragraphs with: - A code example that you then explain - A question that you then answer - A concrete scenario or use case - A contrast ("Unlike X, this approach...") **List variety**: Don't make every list exactly 3 or 5 items. Use 2, 4, 6, or 7 items when the content calls for it. Never pad a list with filler items to reach a round number. **Section length variety**: Vary section lengths. Some sections need 50 words, others need 300. Don't make every section approximately the same length. --- ### Rule S4: Code-to-Prose Ratio Target 40%+ code coverage (code blocks as a percentage of total content). Developer documentation should show, not tell. Every concept explanation should have an accompanying code example within 2 paragraphs. --- ### Rule S5: Enhanced Heading Rules Following Stripe/Twilio/Vercel patterns: - Maximum 3 heading levels per page (H1 → H2 → H3). Never use H4 in a document you write; this skill file itself uses H4 for its own numbered practices, and that is not a template. - One H2 per 200-400 words of body text. - Use sentence case for headings, not Title Case. - Compress structural signals into headings, not opening sentences: - BAD: `## Prerequisites` followed by "Before starting, ensure you have the following installed:" - GOOD: `## Prerequisites: Node.js 18+, plugin SDK` --- ### Rule S6: Enhanced Progressive Disclosure Lead with essentials. Layer details in 5 tiers: 1. One-paragraph overview (what + why) 2. Quick-start example (5-minute version) 3. Detailed walkthrough 4. Reference tables 5. Edge cases and advanced usage Use collapsible sections (`<details>`) for advanced content that most readers skip. **Escape hatches**: At each tier, provide a link forward for users who already know the basics ("Already familiar? Skip to the API reference →"). --- ### Rule S7: Conciseness Every sentence must add new information. Delete: - Introductory throat-clearing ("In this section, we will discuss...") - Repetition of the same point in different words - Filler paragraphs that summarize what's coming next - Conclusions that repeat what was already said --- ### Rule S8: Diagram Requirements Include a diagram where the text describes a flow of 3 or more steps, or an architecture with 3 or more parts. Use whatever format the project's docs already render (Mermaid, SVG, an image); do not add a new diagram toolchain. Diagrams must: - Render in the project's docs (valid syntax for the chosen format) - Match the text they accompany - Add information that prose alone cannot convey (flow, timing, relationships) - Have descriptive labels (not "Step 1", "Step 2") --- ### Rule S9: Enhanced Code Examples Every code example must: