Managing Documentation

Managing Documentation

Comprehensive agent skill for creating, updating, and maintaining high-quality project documentation. Follows established best practices from agile, Google, and Write the Docs methodologies.

When to Use This Skill

Activate when:

• Creating new documentation for projects, features, or products
• Updating or improving existing documentation quality
• Validating documentation against style and inclusivity standards
• Writing guides, API documentation, or README files
• Ensuring documentation works for global, diverse audiences
• Checking for inclusive language and accessibility
• Applying lean/agile documentation principles
• Planning documentation structure and organization
• Reviewing documentation for clarity and completeness

Core Workflows

Workflow 1: Creating New Documentation

Step 1: Define Purpose and Audience

Before writing:

• Clarify purpose: What is this documentation meant to achieve? Who will use it?
  • If unclear, ask user: "What problem should this documentation solve? Who will read it?"
• Identify customers: Actual end-users, developers, operators, support staff?
  • If uncertain, ask user: "Who is the primary audience? What's their experience level?"
• Determine scope: What should be covered? What's out of scope?
  • If uncertain, ask user: "What specific topics must be covered? What can be linked or omitted?"
• Choose doc type: Guide, API reference, README, tutorial, troubleshooting, architecture overview

Step 2: Plan Structure

Follow these principles:

• Skimmable: Use clear headings, start paragraphs with key concepts, use lists
• Cumulative: Order content so prerequisites come first (especially for guides/tutorials)
• Exemplary: Include examples for most concepts, especially in guides and API docs
• Concise: Keep just barely good enough - avoid over-documentation

Structure recommendations:

• Getting Started Guides: Introductory context → prerequisites → step-by-step → examples
• API Documentation: Purpose of API group → parameter descriptions → examples → error cases
• README: Brief intro → installation/quick start → usage → contributing → license
• Troubleshooting: Common problems → diagnostics → solutions with examples

Step 3: Write with Global Audience in Mind

• Use simple, concise language: Avoid idioms, colloquialisms, jargon (unless industry-standard and explained)
• Use active voice and present tense for clarity
• Use shorter sentences - easier to understand and translate
• Define abbreviations on first use
• Avoid phrasal verbs when simpler verbs work (use "start" not "commence")
• Use concrete examples - show don't just tell
• Avoid dated language like "new", "currently", "soon" - focus on what is, not what changed

Example: ❌ "Our product now supports the latest feature" ✅ "Our product supports feature X for use case Y"

Never document future features:

• Don't pre-announce anything unless approved by legal counsel
• Focus on current capabilities, not roadmaps or planned features
• Document what exists now, not what will exist later
• Example: ❌ "Feature X will be available soon" ✅ [omit until released]

Avoid excessive or unverifiable claims:

• Don't use superlatives: "best", "fastest", "simplest", "never", "always"
• Be careful with "ensure" and "guarantee" - use only when truly guaranteed
• Reference data sources for performance claims
• Example: ❌ "Our product is the fastest" ✅ "Our product processes X requests/sec"
• Example: ❌ "Prevents all security attacks" ✅ "Helps prevent attacks by..."
• Example: ❌ "The best solution for your needs" ✅ "A solution that handles X, Y, and Z"

Avoid overusing politeness:

• Don't overuse "please" in instructions - it's implied and adds unnecessary words
• Example: ❌ "Please click the button" ✅ "Click the button"
• Example: ❌ "For more information, please see the guide" ✅ "For more information, see the guide"
• Exception: Use "please" when making significant requests or in sensitive contexts

Step 4: Ensure Inclusivity

Avoid problematic language:

• No ableist terms: ❌ "sanity check" ✅ "final check", ❌ "blind to" ✅ "overlook", ❌ "cripples" ✅ "slows down"
• No gendered terms: ❌ "man-hours" ✅ "person-hours", ❌ "he/she" ✅ "they", avoid gendered pronouns in examples
• No violent language: Avoid "kill", "hit", avoid animal slaughter metaphors
• No culturally specific references, slang, or humor
• Use diverse names in examples

Be specific about people:

• "person with disabilities" not "the disabled"
• "older adults" not "seniors" or "the elderly"
• "quadriplegic person" not "a quadriplegic"
• Research community preferences before writing about disabilities

For code/commands with non-inclusive terms in them, use code formatting and minimize:

• ✅ "Configure the master node (shown in the file)"
• ✅ "Execute the START SLAVE statement"
• Use preferred term in surrounding text

Step 5: Review and Validate

Consider automated documentation generation where appropriate:

• API docs: JSDoc, TSDoc, rustdoc, Sphinx, Doxygen, JavaDoc
• Architecture diagrams: PlantUML, Mermaid diagrams from code
• Dependency graphs: Generated from package managers
• Test reports: Generated from test suites
• Remember: Generated docs still need human review and enhancement

Alternatives when no technical writer available:

• Pair documenting: Write documentation with a partner (like pair programming)
• Shared ownership: Multiple people maintain and improve documentation
• Text-to-speech software: Listen to your writing to find awkward passages
• Peer review: Have colleagues review for clarity before publishing

Before publishing, check:

• Clear purpose defined
• Audience needs addressed
• Examples provided for key concepts
• No jargon without explanation
• Simple language, active voice
• No outdated time-based words (new, currently, soon, latest, now)
• No excessive claims (best, fastest, simplest, never, always)
• No future features mentioned
• No overuse of "please" in instructions
• No ableist, gendered, or violent language
• No culturally specific references
• Consistent terminology throughout
• Concise but sufficient detail
• Headings clear and descriptive
• Links to related info (if applicable)

Workflow 2: Updating Existing Documentation

Step 1: Assess Current State

• Read existing documentation completely
• Identify outdated information
• Check for consistency issues
• Look for jargon without explanation
• Check for problematic language (ableist, gendered, violent, cultural specificity)
• Verify examples still work
• Check clarity for non-expert readers

Step 2: Prioritize Changes

Categorize improvements:

• Critical: Incorrect information, broken examples, high-impact clarity issues
• Major: Consistency problems, missing key examples, jargon not explained, outdated phrasing
• Minor: Grammar, tone refinement, better formatting

Step 3: Update Content

When updating:

• Use "Old approaches" sections for deprecated items (never use dates)
• Preserve working examples while updating references
• Improve clarity by breaking up long paragraphs
• Replace problematic language consistently
• Update jargon explanations
• Ensure consistency with updated terminology

Step 4: Verify Changes

• All examples updated and correct
• No broken links or references
• Terminology consistent throughout
• Language inclusive and accessible
• Clarity improved without removing necessary detail
• Matches current product/feature state

Workflow 3: Validating Documentation Quality

Apply these validation checks:

Content Quality (ARID Principles)

• Accept Repetition: Some business logic will be described multiple ways - this is acceptable
• Skimmable: Readers can quickly find what they need without reading everything
• Exemplary: Common use cases have examples, not everything needs examples
• Consistent: Same term used consistently, same formatting applied systematically
• Current: Reflects actual state of product, not historical or future states

Clarity & Accessibility

• No industry jargon without explanation, or uses "click here" link text
• Sentences under 20 words when possible
• Active voice used primarily
• Present tense used for current capabilities
• Examples provided for important concepts
• Headings clearly describe content below

Inclusive Language

• No ableist language (sanity check, blind to, cripples, dumb, etc.)
• No gendered terms (man-hours, he/she pronouns, actress/actor distinctions)
• No violent figurative language (kill, hit, slaughter metaphors)
• No unnecessary cultural specificity
• Diverse names in examples when people shown
• Neutral language about disabilities

Global Audience

• No colloquialisms, idioms, or slang
• No humor (difficult to translate)
• No geographic specificity (seasons, holidays, sports)
• Dates and times unambiguous and clear
• Simple words chosen over complex synonyms
• No assumed prior knowledge

Completeness

• Key information comprehensive (covers all main topics OR clearly states what's excluded)
• Edge cases addressed or acknowledged
• Error scenarios documented
• Prerequisites clearly stated
• Related topics referenced

Currency

• No "new", "currently", "now", "soon", "latest" references to product features
• Reflects actual capabilities not future plans
• Deprecated features clearly marked if included
• Version-specific info generalized when possible

Workflow 4: Applying Agile/Lean Principles

Documentation should be "just barely good enough" - sufficient for current needs without unnecessary detail.

Document Late, Update Constantly

• Don't document speculative features before they stabilize
• Write documentation towards end of development when you know what you've built
• Document just-in-time when most needed
• Update only when pain of using outdated docs exceeds effort to update

Document with Purpose

• Create documents only when they fulfill clear, important goals
• Focus on what customers actually need, not what you think they should need
• Justify documentation requests: why needed? who benefits? what's the cost?

Prefer Executable Specifications

• Use tests as specifications where possible
• Link to code examples rather than duplicate specifications
• Generate system documentation from code when possible

Choose Best Communication Medium

Documentation is often NOT the best choice:

• Direct conversation > documentation for immediate understanding
• Involved stakeholders > documentation for knowledge transfer
• Well-structured code > documentation for technical details

Documentation becomes increasingly valuable as distance (physical or temporal) makes direct communication more difficult or less practical.

Minimize Document Overlap

• Define scope clearly for each document
• Avoid same information in multiple places
• Use references/links instead of duplication
• Link to single source of truth

Display Information Publicly

• Share models, diagrams, documentation during development
• Use documentation as "information radiator" for team communication
• Status indicators help readers understand context (draft vs. finalized)

Quality Checklist by Document Type

Guides & Tutorials

• Introduces topic gently before technical details
• Prerequisites clearly stated upfront
• Step-by-step instructions are concrete (not abstract)
• Examples build on previous examples (not new problems each time)
• Code examples short (~3-5 lines), not full implementations
• Assumptions about reader knowledge clearly stated
• Next steps or related topics referenced at end

API Documentation

• Purpose of API group explained before diving into individual methods
• Each method shows purpose, parameters, return values
• Examples provided for common use cases
• Error cases documented
• Request/response examples clear and realistic but simplified
• No complex real-world implementations in examples
• Shared terminology used throughout

README Files

• Brief description in opening paragraph
• Installation/quick start section early
• Common use cases covered
• Troubleshooting or FAQ included
• Links to full documentation
• Contributing guidelines if accepting contributions
• License clearly stated

Architecture/System Documentation

• High-level overview comes first
• Diagrams supplement (not replace) text description
• Key concepts explained at high level before details
• Links to code for implementation details
• Major components described (not every detail)
• Clear what's documented vs. what's in code
• Design decisions explained (the "why" not just the "what")

Writing Style Principles

Tone and Voice

• Conversational, friendly, and respectful (not stuffy or overly formal)
• Sound like knowledgeable friend, not textbook or marketing material
• Be human and memorable, but focus on information delivery
• Avoid super-entertaining or super-dry extremes

Things to Avoid

• Buzzwords and unnecessary jargon
• Overly cute, wacky, or zany tone
• Ableist language or problematic figures of speech
• Placeholder phrases ("please note", "at this time")
• Choppy or overly long sentences
• Current pop-culture references (won't age well)
• Excessive exclamation marks
• Mixing or overextending metaphors
• Internet slang or abbreviations (tl;dr, ymmv)

Techniques That Work

• Read aloud - does it sound natural? (not every sentence, but check awkward ones)
• Use transitions between sentences for flow
• Step back and ask "what am I really trying to say?"
• Get colleague feedback on tone and clarity
• Focus on communicating useful info clearly - that's most important

Tool Usage Patterns for This Skill

Finding Documentation Files

• Glob for documentation: **/*.md, **/README.md, **/docs/**, **/documentation/**
• Glob for API docs: **/api/**, **/reference/**, **/swagger/**
• Glob for specific doc types: **/CONTRIBUTING.md, **/CHANGELOG.md, **/LICENSE.md

Validating Content for Problematic Terms

Use Grep to search for terms that violate guidelines:

• Ableist language: "sanity|crazy|insane|blind to|cripple|dumb|stupid"
• Gendered language: "he |she |his |her |man-hours|mankind|actress|waitress"
• Violent language: " kill | hit |STONITH|hang |hung "
• Time-based words: "currently|soon|new |latest|now |presently"
• Excessive claims: "best |fastest|simplest|never |always |ensure |guarantee"
• Politeness overuse: "[Pp]lease click|[Pp]lease see|[Pp]lease enter"
• Future features: "will be |coming soon|planned|roadmap"

Understanding Context Before Writing

• Read source code: Use Read tool to understand features before documenting them
• Find existing patterns: Use Grep to find how similar features are documented
• Check project conventions: Read existing docs to match style and terminology

Large-Scale Operations

• Use Task tool with Haiku for validating 50+ documentation files simultaneously
• Use Task tool for codebase exploration when searching for undocumented features or APIs
• Use Bash tool for running documentation generators or build commands

Example Validation Commands

# Search for ableist terms across all markdown files
grep -r "sanity\|crazy\|insane\|blind to\|cripple\|dumb" docs/

# Find time-based language
grep -r "currently\|soon\|new \|latest" **/*.md

# Check for gendered pronouns
grep -r " he \| she \| his \| her " docs/

Common Issues and Fixes

Implementation Approach

When helping with documentation:

1. Understand context: What's the purpose? Who reads it? What do they need?
2. Assess quality: What's working? What needs improvement?
3. Plan improvements: Prioritize critical → major → minor issues
4. Apply standards: Use clear structure, simple language, inclusive voice
5. Validate: Check against this skill's checklists and principles
6. Iterate: Get feedback, refine, publish

The goal is documentation that is clear, accessible, sufficient for actual needs, and welcoming to readers from all backgrounds.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.