Skill: ivangdavila/documentation (version 1.0.0)

--- name: Documentation description: Technical documentation patterns, structure, maintenance, and avoiding common documentation failures. metadata: category: writing skills: ["documentation", "technical-writing", "readme", "api-docs"] --- ## Structure Hierarchy - README: what it is, how to install, quick example — 5 minutes to first success - Getting Started: guided tutorial for beginners — one complete workflow - Guides: task-oriented ("How to X") — goal-focused, not feature-focused - Reference: exhaustive API/CLI docs — complete but not for learning - Troubleshooting: common errors with solutions — search-optimized ## README Essentials 1. One-sentence description — what problem it solves 2. Installation — copy-paste command that works 3. Quick start — minimal example that actually runs 4. Link to full docs — don't cram everything in README Missing any of these = users bounce before trying. ## Code Examples - Every example must be tested — untested examples rot within months - Show complete runnable code, not fragments — users copy-paste - Include expected output — confirms they did it right - Bad: `client.query(...)` / Good: full script with imports, setup, and output - Version-pin examples: `npm install package@2.1.0` not `npm install package` ## API Documentation - Every endpoint needs: method, path, parameters, request body, response, error codes - Show real request/response bodies — not just schemas - Include authentication in every example — most common missing piece - Document rate limits and pagination upfront — not buried in footnotes - Error responses need as much detail as success responses ## What Gets Outdated - Screenshots — UI changes, screenshots don't - Version numbers — hardcoded versions become wrong - Links — external sites move, break constantly - "Current" anything — write timelessly or add review dates - Feature flags and experimental warnings — often forgotten after GA ## Maintenance Patterns - Docs live next to code — same repo, same PR. Separate repos drift - CI checks for broken links — `markdown-link-check` or equivalent - Runnable examples as tests — if example breaks, build fails - Review date in docs: "Last verified: 2024-01" — signals freshness - Delete aggressively — outdated docs worse than no docs ## Common Failures - Documenting implementation, not usage — users don't care how it works internally - Assuming context — define acronyms, link prerequisites - Wall of text — use headings, bullets, code blocks liberally - "See X for more info" without link — friction kills follow-through - Changelog as documentation — changes ≠ how to use current version ## Writing Style - Imperative mood: "Run the command" not "You can run the command" - Second person: "you" not "the user" - Present tense: "This returns X" not "This will return X" - Short sentences — one idea per sentence - Active voice: "The function returns X" not "X is returned by the function" ## Searchability - Use words users search for — not internal jargon - Error messages verbatim in troubleshooting — users paste exact errors - Multiple ways to describe same thing — alias common variations - H2/H3 headings are SEO — match user queries - Avoid clever titles — "Getting Started" beats "Your Journey Begins" ## Versioned Documentation - Major versions need separate docs — v1 users shouldn't see v2 docs - Migration guides between versions — step-by-step, not just changelog - Default to latest stable, link to older versions - Mark deprecated features clearly — don't just remove - URL structure: `/docs/v2/` not query params ## README Anti-patterns - Badge spam — 15 badges before content - Massive feature lists — save for marketing page - No installation instructions — assuming everyone knows - Screenshots without context — what am I looking at? - License-only README — legal compliance ≠ documentation


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)