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 Under 25 Words **Why**: Comprehension drops 30% when sentences exceed 30 words **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) ``` --- ## 7 Ready-to-Use Templates ### Template 1: README Quick Start **Purpose**: Project landing page with 5-minute setup **Max Length**: 80 lines **Use When**: Creating project README ```markdown # [Project Name] [One-line description of what this does] ## Quick Start ```bash # Step 1: Install npm install my-tool # Step 2: Initialize npx my-tool init # Step 3: Start npx my-tool start ``` Visit http://localhost:3000 That's it! ## Features - Feature 1 (one-line description) - Feature 2 (one-line description) - Feature 3 (one-line description) [See detailed feature list](docs/features.md) ## Documentation - [Installation Guide](docs/installation.md) - Complete setup instructions - [Configuration](docs/configuration.md) - All configuration options - [API Reference](docs/api.md) - Complete API documentation - [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions ## Community - [Contributing](CONTRIBUTING.md) - How to contribute - [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines - [Discussions](https://github.com/user/repo/discussions) - Ask questions ## License MIT - See [LICENSE](LICENSE) for details ``` --- ### Template 2: TSDoc Function Documentation **Purpose**: Document TypeScript functions **Format**: TSDoc standard **Use When**: Documenting public APIs ```typescript /** * Retrieves a user by their unique identifier. * * @remarks * This function includes user permissions and preferences in the response. * Results are cached for 5 minutes to reduce database load. * * @param id - User unique identifier (UUID format) * @param options - Optional fetch configuration * @param options.includePermissions - Include user permissions (default: true) * * @returns Promise resolving to User object with permissions * * @throws {NotFoundError} If user with given ID doesn't exist * @throws {UnauthorizedError} If caller lacks 'read:users' permission * * @example * Basic usage: * ```typescript * const user = await getUserById('user-123'); * console.log(user.name, user.email); * // Output: John Doe john@example.com * ``` * * @example * Error handling: * ```typescript * try { * const user = await getUserById('user-123'); * } catch (error) { * if (error instanceof NotFoundError) { * console.error('User not found'); * } * } * ``` * * @see {@link createUser} for creating new users * @since 2.0.0 * @public */ ``` --- ### Template 3: Error Documentation **Purpose**: Document common errors and solutions **Organization**: By symptom **Use When**: Creating troubleshooting guides ```markdown # Troubleshooting Guide ## Installation Issues ### Error: EACCES permission denied **Symptom**: npm install fails with permission error **Full Error Message**: ``` npm ERR! code EACCES npm ERR! syscall access npm ERR! path /usr/local/lib ``` **Cause**: Trying to install globally without proper permissions **Solution**: **Option 1 (Recommended)**: Install locally ```bash npm install --save-dev my-tool npx my-tool ``` **Option 2**: Fix npm permissions ```bash mkdir ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH ``` **Prevention**: Use local installation (avoid -g flag) --- ### Error: Module not found **Symptom**: Import fails with "Cannot find module 'X'" **Causes**: 1. Package not installed 2. Wrong import path 3. TypeScript configuration issue **Solution**: **Step 1**: Verify package is installed ```bash npm list my-package ``` **Step 2**: Check import path matches package name ```typescript // CORRECT import { func } from 'my-package'; // WRONG import { func } from 'my-package/lib/index'; ``` **Prevention**: Always install dependencies before importing ``` --- ### Template 4: Tutorial Structure **Purpose**: Teach by doing **Length**: 15-30 minutes **Use When**: Creating beginner tutorials ```markdown # Tutorial: Building Your First REST API **What you'll learn**: - How to create a basic REST API - How to define routes and handlers - How to connect to a database - How to handle errors **Prerequisites**: - [ ] Node.js 18+ installed ([Download](https://nodejs.org)) - [ ] Basic JavaScript knowledge - [ ] Text editor (VS Code recommended) **Estimated time**: 30 minutes