Documentation Authoring

Workflow Router

Do any docs already exist?
  |
  NO --> GREENFIELD DOCS (new project, no docs)
  |       Phases: Analyze -> Plan -> Write -> Verify
  |
  YES --> What type of change?
           |
           +-> Code changed, docs not updated
           |     --> DOC REFRESH (brownfield)
           |     Phases: Analyze -> Audit Existing -> Drift Detection -> Write (delta) -> Verify
           |
           +-> New feature/module needs documenting
           |     --> DOC ENHANCEMENT (brownfield)
           |     Phases: Analyze -> Audit Existing -> Plan (delta) -> Write -> Verify
           |
           +-> Docs exist but quality/structure is poor
           |     --> DOC AUDIT (brownfield)
           |     Phases: Analyze -> Audit Existing -> Plan -> Rewrite -> Verify
           |
           +-> User wants a specific doc rewritten
           |     --> TARGETED REWRITE (brownfield)
           |     Phases: Analyze -> Audit Existing (single doc) -> Write (replace) -> Verify
           |
           +-> User wants a specific new doc (README, API ref, etc.)
           |     --> TARGETED NEW DOC
           |     Phases: Analyze -> Write (specific) -> Verify
           |
           +-> Version bump or migration
                 --> VERSION UPDATE (brownfield)
                 Phases: Analyze -> Audit Existing -> Drift Detection -> Write (delta) -> Verify

Phase 0: Analyze Repository

What to discover

1. Language and runtime: Identify from manifest files (package.json, pyproject.toml, go.mod, etc.)
2. Framework and libraries: Scan dependencies for framework signatures
3. Architecture: Directory layout, monorepo indicators, service boundaries
4. Entry points: main() functions, CLI interfaces, HTTP servers, scripts
5. Public interfaces: Exported functions, API endpoints, CLI commands
6. Configuration: Environment variables, config files, feature flags
7. Data models: ORM definitions, schemas, migrations
8. Tests and CI: Test frameworks, CI/CD config, build commands
9. Existing documentation: README, docs/ folder, inline docstrings, CLAUDE.md, wiki references
10. Dependencies: External services, databases, APIs consumed

How to explore

• Read README.md and CLAUDE.md first (if they exist)
• Read manifest files (package.json, pyproject.toml, go.mod, Cargo.toml, etc.)
• Scan directory structure to identify modules and services
• Read 2-3 key source files to absorb patterns and conventions
• Check for existing doc infrastructure (Sphinx conf, JSDoc config, OpenAPI specs)
• Look for CI config that builds or tests documentation

Output: Repository Profile

Language: [language and version]
Framework: [framework and version]
Architecture: [monolith, microservices, library, CLI tool, etc.]
Entry points: [main files, CLI commands, HTTP servers]
Public API surface: [exported functions, endpoints, commands]
Config: [env vars, config files]
Test setup: [framework, runner command, coverage]
Existing docs: [what exists, what's missing, what's stale]
Doc infrastructure: [generators, linters, CI checks]

Phase 1: Audit Existing Documentation (Brownfield Only)

Read every existing doc

1. Read it fully. Do not skim. Absorb its structure, voice, and content.
2. Classify its Diataxis type (Tutorial, How-to, Reference, Explanation, or Hybrid).
3. Note its conventions: heading style, code block formatting, terminology, section ordering, tone.
4. Assess accuracy by spot-checking 3-5 factual claims against source code.
5. Assess completeness by comparing documented interfaces against actual public interfaces found in Phase 0.

Existing doc inventory

Existing Documentation Inventory
  [file path] | [diataxis type] | [accuracy: high/medium/low] | [completeness: high/medium/low]
  README.md   | hybrid          | medium (install cmd outdated) | low (missing API section)
  docs/api.md | reference       | low (3 endpoints missing)     | medium
  ...

Identify what to preserve

Brownfield conventions contract

• Heading style: What levels are used? Are they noun phrases or verb phrases?
• Code block language tags:

  bash

  vs

  shell

  vs

  sh

  ?

  javascript

  vs

  js

  ?
• Terminology: What terms does the project use? ("service" vs "server", "endpoint" vs "route", "config" vs "configuration")
• Section ordering: What comes first? How are things grouped?
• Tone: Formal or casual? First-person or impersonal?

Phase 2: Plan Documentation

Greenfield planning

Diataxis classification

Documentation plan algorithm

1. Always include: README.md (hybrid: summary + links to other docs)
2. For each knowledge area, decide if a separate doc is needed:

1. Omit irrelevant sections. No API means no API docs. No CLI means no CLI usage.
2. Merge or split by project size:
   • Small projects: combine Installation, Usage, and Overview in README
   • Large projects: separate into focused files under docs/
3. Order by audience need: Getting Started before deep reference. Overview before architecture.

Plan output

Documentation Plan
- README.md (hybrid) — CREATE
- docs/getting-started.md (tutorial) — CREATE
- docs/architecture.md (explanation) — CREATE
- docs/api-reference.md (reference) — CREATE
- CONTRIBUTING.md (how-to) — CREATE

Brownfield planning

Doc Refresh: Drift detection

Drift Report: [file path]
  STALE:    [fact in doc] → [current fact in code]
  MISSING:  [interface/feature not documented]
  DEAD:     [documented item that no longer exists]
  ACCURATE: [sections that are still correct]

Doc Enhancement: Delta plan

1. Identify which EXISTING docs need updating (e.g., README features list, API reference for new endpoints)
2. Identify which NEW docs need creating
3. For each existing doc, specify ONLY what changes — do not rewrite

Documentation Delta Plan
- README.md (hybrid) — MODIFY: add new feature to Features section, update Quick Start
- docs/api-reference.md (reference) — MODIFY: add POST /widgets endpoint
- docs/widget-guide.md (how-to) — CREATE: new guide for widget feature

Doc Audit: Restructure plan

1. List all issues found in Phase 1 with severity
2. Propose fixes grouped by severity (Critical → High → Medium → Low)
3. For each doc, specify: KEEP (as-is), EDIT (fix specific issues), REWRITE (replace with new version), or DELETE (remove dead doc)
4. Present to user for approval — let them decide scope

Audit Findings & Plan
  README.md:
    - [Critical] Install command references removed package → EDIT: fix command
    - [High] Missing API section → EDIT: add section
    - [Low] Mixed tutorial and reference content → EDIT: extract tutorial to separate doc
  docs/old-guide.md:
    - [Critical] Entire doc references removed feature → DELETE
  docs/api.md:
    - [Medium] 3 endpoints undocumented → EDIT: add missing endpoints

Targeted Rewrite: Single-doc plan

1. Read the existing doc fully (done in Phase 1)
2. Identify what to PRESERVE (domain knowledge, rationale, custom sections)
3. Identify what to REPLACE (stale facts, broken examples, wrong structure)
4. Identify what to ADD (missing content)
5. Present the plan: "I will keep X, replace Y, add Z"

Rewrite Plan: README.md
  PRESERVE: Project description, design rationale in Architecture section
  REPLACE:  Install commands (outdated), Quick Start (broken example),
            Features list (missing 3 features)
  ADD:      Configuration section, link to new API docs
  REMOVE:   FAQ section (answers belong in specific docs)

Version Update: Migration plan

1. Identify all version-specific references in existing docs
2. Identify breaking changes (from changelog, git diff, or user input)
3. Plan updates grouped by: version numbers, API changes, config changes, behavioral changes, deprecation notices

Version Update Plan: v1 → v2
  Version references: README.md (3), docs/install.md (2), docs/api.md (header)
  Breaking changes:
    - POST /users now requires `email` field → docs/api-reference.md
    - Config key `db_host` renamed to `database_url` → docs/deployment.md, README.md
  Deprecations:
    - GET /users/search deprecated in favor of query params on GET /users → docs/api-reference.md
  New features:
    - Batch API endpoints → docs/api-reference.md (add section)

Phase 3: Write Documentation

Greenfield: Write from scratch

Writing sequence

1. README.md first (it's the front door; forces you to articulate purpose)
2. Getting Started (validates that setup works)
3. Reference docs (API, CLI usage — factual, derived from code)
4. How-to guides (developer guide, deployment, contributing)
5. Explanation docs (architecture, design decisions)
6. Changelog (if applicable)

Per-document process (greenfield)

1. Classify: Confirm Diataxis type. Apply that type's rules strictly.
2. Gather facts: Read the relevant source code, config, and tests. Never write about code you haven't read.
3. Draft: Use the template from references/doc-templates.md. Follow the writing rules from references/writing-rules.md.
4. Verify examples: Every code example, command, or snippet must be derived from actual code. Never fabricate examples.
5. Cross-reference: Link to related docs. Never duplicate content that belongs in another document.

Brownfield: Edit existing docs

Per-document process (brownfield)

1. Re-read the doc. Confirm your understanding from Phase 1.
2. Apply only planned changes. Follow the delta plan from Phase 2. Do NOT restructure, restyle, or "improve" sections outside scope.
3. Match existing conventions. Use the same heading style, terminology, code block formatting, and tone discovered in Phase 1.
4. Preserve valuable content. Domain knowledge, design rationale, user tips, and custom sections survive unless explicitly marked for removal.
5. Verify every edit. Each changed fact must be verified against code.
6. Minimize diff. Change only what needs changing. Smaller diffs are easier to review and less likely to introduce errors.

Brownfield-specific rules

• Edit, don't rewrite. Unless the user requests a rewrite, modify the existing doc surgically. Fix the wrong facts; leave correct content alone.
• Match existing style. If the existing README uses

  ##

  for sections and

  bash

  for code blocks, continue that pattern. Do NOT switch to

  ###

  or

  shell

  because you prefer it.
• Preserve structure. Keep the existing section ordering unless it's part of the planned changes. Users have muscle memory for where information lives.
• Preserve authorship signals. If existing docs have a distinctive voice, project-specific terminology, or custom sections, maintain them. The original author's domain knowledge is irreplaceable.
• Never silently delete content. If a section needs removal, note it in your plan and confirm with the user. Content that looks outdated may contain context you can't reconstruct from code.
• Refactor only what you're asked to change. Do NOT improve adjacent sections, fix unrelated formatting, or add sections not in the plan. This mirrors the TDD principle: "refactor only what you wrote."

Targeted Rewrite process

1. Create from the approved plan. Write the new version using the PRESERVE/REPLACE/ADD/REMOVE breakdown from Phase 2.
2. Start from the template in references/doc-templates.md, then transplant preserved content into the new structure.
3. For preserved content: Copy it verbatim. Do not rephrase domain knowledge or design rationale unless it's factually wrong.
4. For replaced content: Write fresh from code analysis. Verify every fact.
5. For added content: Follow greenfield per-document process.
6. Present the full new doc for review before replacing the existing file.

Shared: README generation

• Title + one-line description (what is this, what problem does it solve)
• Badges (optional: build status, coverage, version)
• Installation (copy-paste commands, minimal steps)
• Quick start (runnable example with sample output)
• Key features (bullet list of capabilities)
• Usage examples (code blocks with real commands/code)
• Architecture overview (brief summary or link to architecture doc)
• Development (how to build/test, or link to developer guide)
• Contributing (link to CONTRIBUTING.md)
• License

Shared: API reference generation

1. Parse the code to identify all public interfaces (exports, endpoints, commands)
2. For each interface, document: signature/URL, parameters, return type, authentication, example request, example response, error cases
3. Mirror the code structure in the doc structure (classes, modules, endpoints)
4. If OpenAPI/Swagger exists, use it as the canonical source
5. Follow Reference type rules: austere, factual, no instruction or explanation

Shared: Architecture documentation

1. System Context: What is this system? What external systems and users interact with it? (No technical detail — readable by non-technical people)
2. Container diagram: What are the major deployable units (apps, databases, queues)? What technologies? How do they communicate?
3. Component diagram: (Optional) Inside a container, what are the major modules and their responsibilities?

Shared: Changelog generation

• Name the file

  CHANGELOG.md

• Maintain an "Unreleased" section at the top
• Use reverse chronological order
• Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security
• Use ISO 8601 dates (YYYY-MM-DD)
• Never use raw git log as a changelog

Phase 4: Verify Documentation

Verification checklist (all workflows)

• Accuracy: Every factual claim matches the code
• Commands work: Every shell command runs successfully
• Code examples compile/run: Every code snippet is valid
• Links resolve: All internal links point to existing files/headings
• Completeness: All public interfaces are documented (for reference docs)
• No fabrication: No invented API endpoints, flags, or behaviors
• Type purity: Each doc stays within its Diataxis type (no mixing)
• Consistent terminology: Same term used for same concept everywhere
• Config matches code: Documented env vars, versions, and settings match actual code
• No duplication: Content lives in one place and is linked elsewhere

Additional brownfield verification

• Preserved content intact: Domain knowledge, rationale, and custom sections from existing docs were not lost or mangled
• Conventions maintained: Heading style, terminology, code block formatting match the rest of the existing docs
• No unplanned changes: Only the sections identified in the delta plan were modified. No drive-by formatting fixes or unsolicited rewrites.
• No content silently deleted: Every removal was in the approved plan
• Diff is minimal: Changes are surgical, not a full rewrite (unless Targeted Rewrite was the chosen workflow)
• Existing cross-references still work: Changes didn't break links in OTHER docs that point to modified sections

Verification method

1. Spot-check facts against source code (grep for documented functions, endpoints, env vars — confirm they exist)
2. Test commands by reading them critically against the codebase (do the referenced files, scripts, and flags exist?)
3. Validate examples against actual code signatures and return types
4. Check cross-references (do linked files and headings exist?)
5. Run doc linters if the project has them (markdownlint, link checkers)
6. (Brownfield) Compare against original to confirm only planned changes were made and preserved content survived

Common errors to catch

Phase 5: Maintenance Strategy

Docs-as-code principles

• Version docs alongside code. All docs live in the repo, not a wiki.
• Update docs in the same commit as code changes. Never defer.
• Review docs in PRs. Reviewers should reject PRs that change behavior without updating docs.
• Delete dead docs. Outdated documentation is worse than no documentation. Remove or mark deprecated.
• Link, don't duplicate. Point to canonical sources rather than copying.

Automated checks (recommend to user)

Failure Recovery

Documentation issue
  |
  +-> Can't determine what code does
  |     +-> Read more source files
  |     +-> Check tests for behavioral clues
  |     +-> Ask user for clarification
  |
  +-> Conflicting information (code vs. config vs. comments)
  |     +-> Code is authoritative (it's what actually runs)
  |     +-> Note the conflict; update incorrect sources
  |
  +-> Unsure if feature is public or internal
  |     +-> Check exports, access modifiers, public API markers
  |     +-> When in doubt, document it (users may depend on it)
  |     +-> Ask user if unclear
  |
  +-> Existing docs are extensive but wrong (brownfield)
  |     +-> Fix accuracy first, preserve structure
  |     +-> Never rewrite from scratch unless user requests it
  |     +-> Track changes for user review
  |
  +-> Existing doc has valuable content mixed with stale content (brownfield)
  |     +-> Separate: identify each section as preserve/replace/add/remove
  |     +-> Fix the stale parts, keep the valuable parts
  |     +-> When uncertain, preserve and flag for user review
  |
  +-> Conventions in existing docs conflict with best practices (brownfield)
        +-> Follow existing conventions (consistency > correctness)
        +-> Only change conventions if user explicitly requests it
        +-> If existing convention causes real problems (e.g., broken rendering),
            fix that specific issue and note the change

Reference Files

• Document templates: See references/doc-templates.md for README, API Reference, Architecture, Developer Guide, Contributing, Changelog, Getting Started, ADR, and Testing templates
• Diataxis guide: See references/diataxis-guide.md for the four documentation types with do/don't rules, voice, and structure
• Repository analysis: See references/repo-analysis.md for the systematic codebase analysis method
• Drift detection: See references/drift-detection.md for the section-by-section method to identify doc/code divergence
• Writing rules: See references/writing-rules.md for style guide, formatting rules, and quality checklist