Documentation Expert Guide

Your agent for improving documentation quality across software projects — establishing standards, writing clear technical content, and maintaining documentation that developers actually use.

When to Use This Agent

Choose Documentation Expert Guide when:

• Improving existing documentation for clarity, accuracy, and completeness
• Establishing documentation standards and templates for a project
• Writing inline code documentation (comments, docstrings, JSDoc)
• Creating README files, contributing guides, and project documentation
• Auditing documentation coverage and identifying gaps

Consider alternatives when:

• You need API documentation (OpenAPI specs) — use a documentation engineer agent
• You need a full documentation site (Docusaurus, MkDocs) — use a Docusaurus expert
• You need technical blog posts — use a technical writer agent

Quick Start

Copy
# .claude/agents/documentation-expert.yml
name: Documentation Expert Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Documentation quality agent for improving technical docs, establishing standards, and maintaining developer documentation

Example invocation:

claude "Audit the documentation in our project — identify undocumented public functions, stale README sections, and missing setup instructions"

Core Concepts

Documentation Quality Criteria

Criterion	Description	Test
Accurate	Matches current code behavior	Follow the docs — do they work?
Complete	Covers all public interfaces	Any undocumented public API?
Current	Reflects latest version	When was it last updated?
Findable	Easy to discover and search	Can users find what they need?
Concise	Says enough, not too much	Can anything be removed?
Actionable	Tells readers what to do	Clear next steps?

Documentation Pyramid

            ┌──────────┐
            │ Getting   │  ← First thing users read
            │ Started   │     Must work perfectly
            ├──────────┤
            │ How-To    │  ← Problem-specific guides
            │ Guides    │     Task-oriented
            ├──────────┤
            │ Reference │  ← Complete API docs
            │ Docs      │     Generated from code
            ├──────────┤
            │ Internal  │  ← Architecture, ADRs
            │ Docs      │     Team knowledge
            └──────────┘

Configuration

Parameter	Description	Default
doc_scope	Documentation scope (readme, api, guides, all)	all
code_doc_style	Code comment style (jsdoc, tsdoc, pydoc)	auto-detect
quality_standard	Quality bar (minimal, standard, comprehensive)	standard
audit_mode	Check completeness without modifying	false
language	Documentation language	english

Best Practices

1. Document the "why" alongside the "what." Function signatures tell you what code does. Comments should explain why it does it that way. "Sort by timestamp descending because the UI displays newest first" is useful context that the code alone doesn't convey.

2. Keep documentation close to the code it describes. Inline documentation (JSDoc, docstrings) stays current because it's visible during code changes. External docs in separate directories drift because developers forget to update them.

3. Test documentation like code. Run getting-started guides on clean environments. Validate code examples compile and run. Check that documented endpoints return the described responses. Untested documentation is unreliable documentation.

4. Write for the reader who knows nothing about your project. New team members, open-source contributors, and future-you will read your docs. Don't assume context — explain acronyms, link to prerequisites, and provide complete setup instructions.

5. Remove documentation that's worse than none. Stale documentation that describes old behavior is actively harmful — it sends users down wrong paths. If you can't keep documentation current, delete it and leave a note about where to find current information.

Common Issues

Documentation and code are out of sync. Docs written separately from code diverge quickly. Use code-generated documentation (TypeDoc, Sphinx, GoDoc) for API references, and include documentation updates in PR review checklists for guides and READMEs.

README is too long and unfocused. READMEs that try to cover everything become unreadable. Keep the README focused on: what the project does, how to install it, and how to use it. Move detailed guides, architecture docs, and contribution guidelines to separate files.

Nobody writes documentation because there's no template. Remove friction by providing documentation templates for common types (function docs, module READMEs, ADRs). When the template exists, writing becomes filling in fields rather than starting from a blank page.