Workflow: Docs Auto-Generator

Documentation that writes itself. Transform code changes into updated READMEs, API references, and changelogs—ensuring your docs are always current without the manual maintenance burden.

Documentation is the orphan of software development. Everyone agrees it's important, yet it constantly falls out of date. APIs change but docs don't. Features ship without explanation. New team members struggle because onboarding materials reference old interfaces.

The Docs Auto-Generator workflow changes the equation by making documentation a byproduct of development, not a separate task. As you code, Claude Cowork analyzes changes and updates the relevant documentation automatically—keeping READMEs fresh, API docs accurate, and changelogs comprehensive.

Why This Matters

Documentation debt compounds faster than code debt. This workflow prevents that accumulation:

  • Accuracy: Docs reflect the actual codebase
  • Completeness: No forgotten features or endpoints
  • Consistency: Uniform style across all documentation
  • Velocity: Ship features without documentation delays

The ROI is continuous:

  • Reduce onboarding time for new developers by 50%
  • Cut support tickets asking "how do I...?"
  • Enable self-service API integration for customers
  • Maintain professional polish without dedicated tech writers

The Goal: Your Complete Documentation Pipeline

This workflow creates living documentation that evolves with your code:

1. README Maintenance

Keep your project's front door welcoming:

  • Feature Lists: Automatically updated capability lists
  • Installation Instructions: Reflect current dependencies
  • Quick Start: Working examples from actual code
  • Configuration: Documented environment variables
  • Badges & Status: Current build, version, and coverage info

2. API Documentation

Auto-generated from source:

  • Endpoint References: Paths, methods, parameters
  • Request/Response Examples: Real working samples
  • Authentication: Current auth methods and examples
  • Error Codes: Documented with explanations
  • SDK Examples: Code samples in multiple languages

3. Changelog Generation

Track every change automatically:

  • Versioned Releases: Organized by semantic version
  • Categorized Changes: Features, fixes, breaking changes
  • Migration Guides: Instructions for major updates
  • Contributor Credits: Automatic attribution
  • Deprecation Notices: Early warnings for removal

4. Code Documentation

Inline docs that stay current:

  • Docstrings: From function signatures and comments
  • Type Documentation: From type hints and interfaces
  • Architecture Diagrams: Generated from module relationships
  • Dependency Maps: Visualize code relationships
  • Usage Examples: Extracted from test files

5. Knowledge Base

Comprehensive team documentation:

  • Onboarding Guides: Current setup instructions
  • Architecture Decisions: ADRs extracted from code comments
  • Troubleshooting: Common issues and solutions
  • Best Practices: Patterns from code review
  • Runbooks: Operational procedures

The Setup: Building Your Documentation Factory

Prerequisites

Required Tools:

  1. Code Repository: Access to your codebase
  2. Existing Docs: README, docs folder, or wiki
  3. Claude Cowork: With code-reader and documentation skills
  4. Documentation Format: Markdown, reStructuredText, or custom

Optional Enhancements:

  • Documentation Generators: MkDocs, Docusaurus, Sphinx
  • API Tools: Swagger/OpenAPI, Postman
  • Diagram Tools: Mermaid, PlantUML
  • Hosting: GitHub Pages, Netlify, ReadTheDocs

Step-by-Step Configuration

Step 1: Documentation Inventory

Audit your current documentation:

# Find all documentation files
find . -type f \( -name "*.md" -o -name "*.rst" -o -name "*.txt" \) \
  ! -path "./node_modules/*" \
  ! -path "./.git/*" \
  ! -path "./venv/*" \
  > .claude-docs/inventory.txt

Step 2: Configuration File

Create .claude-docs/config.yaml:

documentation:
  project_name: "MyAPI"
  description: "REST API for user management"
  version_source: "package.json"  # or pyproject.toml, etc.

  readme:
    path: "README.md"
    sections:
      - title: "Installation"
        source: "setup.py"
      - title: "Quick Start"
        source: "examples/"
      - title: "API Reference"
        source: "src/routes/"
      - title: "Configuration"
        source: "config/"

  api_docs:
    path: "docs/api/"
    format: "markdown"  # or "openapi", "postman"
    extract_from:
      - "src/routes/*.py"
      - "src/controllers/*.py"
    include_examples: true
    example_source: "tests/"

  changelog:
    path: "CHANGELOG.md"
    format: "keep-a-changelog"
    commit_source: "git log"
    categorize_by:
      - "feat:"
      - "fix:"
      - "docs:"
      - "breaking:"

  code_docs:
    path: "docs/code/"
    extract_docstrings: true
    include_private: false
    include_tests: false

  wiki:
    path: "docs/wiki/"
    pages:
      - "onboarding.md"
      - "architecture.md"
      - "troubleshooting.md"
      - "deployment.md"

Step 3: The Master Prompt

Run the Docs Auto-Generator protocol on this codebase:

Repository: [path or git URL]
Current Version: [version number]
Last Documentation Update: [date]

1. README ANALYSIS & UPDATE
   Review and update README.md:

   **Current State Analysis:**
   - Read existing README
   - Identify outdated sections
   - Note missing information
   - Check broken links

   **Code Analysis:**
   - Scan package.json/pyproject.toml for dependencies
   - Check src/ for main features
   - Review examples/ for working code
   - Look at tests/ for usage patterns

   **Generated Updates:**

   ### Installation Section
   ```markdown
   ## Installation

   ```bash
   npm install mypackage
   # or
   yarn add mypackage

Requirements:

  • Node.js >= 16.0
  • [Other dependencies from package.json]

### Quick Start
Extract from examples/:
```markdown
## Quick Start

```javascript
// From examples/basic-usage.js
[Working example code]


### Features
List from src/ structure:
```markdown
## Features

- [Feature name]: [Description from code]
- [Feature name]: [Description from code]

API Overview

Summary of main exports:

## API

#### `functionName(params)`
[Description from JSDoc/docstring]

**Parameters:**
- `param1` (type): Description
- `param2` (type): Description

**Returns:** (type) Description

Configuration

From config/ and environment:

## Configuration

Environment variables:
- `API_KEY`: Your API key
- `ENDPOINT`: API endpoint URL

Present changes as:

- Old content
+ New content

  1. API DOCUMENTATION GENERATION Generate comprehensive API docs:

    Endpoint Discovery: Scan source files for API routes:

    • HTTP methods (GET, POST, PUT, DELETE)
    • Path patterns
    • Parameters (path, query, body)
    • Response types

    For Each Endpoint:

    ### POST /api/v1/users

Create a new user account.

**Authentication:** Bearer token required

**Request Body:**
```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member"
}

    Response 201:

    {
  "id": "usr_123",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2026-02-09T10:00:00Z"
}

    Response 400:

    {
  "error": "Validation failed",
  "details": ["Email is required"]
}

    Example Request:

    curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"John"}'

    
**SDK Examples:**
Provide code samples:
```javascript
// JavaScript
const client = new MyAPI({ apiKey: 'your-key' });
const user = await client.users.create({
  email: 'user@example.com',
  name: 'John Doe'
});

    # Python
from myapi import Client
client = Client(api_key='your-key')
user = client.users.create(
    email='user@example.com',
    name='John Doe'
)

  2. CHANGELOG UPDATE Generate changelog entries:

    Since Last Version: Review git commits since last tag:

    git log v1.2.0..HEAD --oneline --no-merges

    Categorize Changes:

    ## [1.3.0] - 2026-02-09

### Added
- New feature X that does Y
- Support for Z functionality
- [From commits with "feat:" prefix]

### Changed
- Improved performance of endpoint
- Updated dependency versions
- [From commits with "refactor:" or "perf:"]

### Deprecated
- Old API method (will be removed in v2.0)
- [From deprecation notices in code]

### Removed
- Dropped support for Node 14
- [From breaking changes]

### Fixed
- Bug where X would cause Y
- [From commits with "fix:" prefix]

### Security
- Patched vulnerability in dependency
- [From security advisories]

    Migration Guide (if breaking changes):

    ### Migrating from 1.2.x to 1.3.0

#### Breaking Change: API Response Format
The `user` endpoint now returns a nested object:

```javascript
// Before
const name = response.name;

// After
const name = response.data.name;

  3. CODE DOCUMENTATION Extract inline documentation:

    From Docstrings/JSDoc:

    ## Module: auth.js

### `authenticateUser(credentials)`

Authenticates a user with email and password.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| credentials | Object | Login credentials |
| credentials.email | string | User's email address |
| credentials.password | string | User's password |

**Returns:** `Promise<AuthResult>`

**Throws:**
- `InvalidCredentialsError` - When email/password don't match
- `AccountLockedError` - When account is temporarily locked

**Example:**
```javascript
try {
  const result = await authenticateUser({
    email: 'user@example.com',
    password: 'secret123'
  });
} catch (error) {
  console.error('Login failed:', error.message);
}

    
**Architecture Overview:**
Generate from module structure:
```markdown
## Architecture

    src/ ├── auth/ # Authentication logic ├── api/ # HTTP route handlers ├── models/ # Data models ├── services/ # Business logic └── utils/ # Helper functions

    
### Data Flow
1. Request → API routes
2. Authentication middleware
3. Controller logic
4. Service layer
5. Database models

  4. WIKI/KNOWLEDGE BASE Update team documentation:

    Onboarding Guide:

    # New Developer Onboarding

## Day 1: Setup
1. Clone repository
2. Run `npm install`
3. Copy `.env.example` to `.env`
4. Run tests: `npm test`

## Day 2: First Contribution
- Pick an issue labeled "good first issue"
- Follow the PR template
- Request review from [team lead]

    Troubleshooting: Extract from code comments and issues:

    ## Common Issues

### "Cannot connect to database"
**Cause:** Environment variables not set
**Solution:** Check DATABASE_URL in .env

### "Tests failing locally"
**Cause:** Test database not initialized
**Solution:** Run `npm run test:setup`

  5. DOCUMENTATION QUALITY CHECK Verify completeness:

    Coverage Report:

    • [ ] All public functions documented
    • [ ] All API endpoints documented
    • [ ] All environment variables listed
    • [ ] All breaking changes noted
    • [ ] Examples are runnable
    • [ ] No broken links

    Consistency Check:

    • [ ] Same terminology throughout
    • [ ] Consistent code style in examples
    • [ ] Uniform heading structure
    • [ ] Matching version numbers

Guidelines:

  • Preserve existing documentation style
  • Add examples for every feature
  • Note deprecated features with alternatives
  • Include error handling in examples
  • Keep language simple and clear
  • Update dates and version numbers

**Step 4: Automation Setup**

**GitHub Actions Workflow:**

```yaml
name: Documentation
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate Documentation
        run: |
          claude "Run Docs Auto-Generator protocol"

      - name: Commit Changes
        run: |
          git config user.name "Docs Bot"
          git config user.email "docs@example.com"
          git add docs/ README.md CHANGELOG.md
          git diff --staged --quiet || git commit -m "docs: Update documentation"
          git push

Pre-Commit Hook:

#!/bin/bash
# Check if documentation needs updates
if git diff --cached --name-only | grep -q "\.py$\|\.js$\|\.ts$"; then
    echo "Code changed. Consider running: claude-docs-update"
fi

Real-World Use Cases

Case Study 1: API-First Startup

Before: API documentation was manually maintained in Postman. Every endpoint change required manual updates. Docs were frequently out of sync with the actual API.

After: Automated documentation pipeline:

  • OpenAPI spec generated from code annotations
  • Request/response examples extracted from tests
  • Changelog auto-generated from commits
  • SDK examples updated automatically

Result: Documentation accuracy improved to 100%. Developer onboarding time dropped from 3 days to 2 hours. Support tickets about API usage decreased 70%.

Case Study 2: Open Source Library

Before: README was comprehensive but quickly outdated. Contributors struggled to understand the codebase. Changelog was inconsistently maintained.

After: Living documentation:

  • README auto-updates from package metadata
  • API docs generated from JSDoc comments
  • Changelog created from conventional commits
  • Contributing guide extracted from PR templates

Result: First-time contributor PRs increased 40%. Issues asking "how do I..." dropped 60%. The project maintainer spent 50% less time on documentation tasks.

Case Study 3: Enterprise Platform

Before: Multiple teams maintained separate documentation in Confluence, READMEs, and PDFs. Information was scattered and often contradictory.

After: Centralized documentation generation:

  • Architecture docs from code structure
  • API reference from service definitions
  • Runbooks from operational scripts
  • Onboarding from setup automation

Result: New engineer onboarding reduced from 2 weeks to 3 days. Cross-team communication improved with single source of truth. Audit documentation was always current.

Advanced Customization

Custom Templates

Define your documentation structure:

templates:
  readme:
    sections:
      - header: "# {project_name}\n\n{description}"
      - badges: "[![Build](...)]"
      - toc: "auto-generated"
      - installation: "from setup.py"
      - usage: "from examples/"
      - api: "from src/"
      - contributing: "from CONTRIBUTING.md"

Multi-Language Support

Generate docs in multiple languages:

localization:
  languages:
    - en
    - es
    - de
  translate:
    - README.md
    - docs/getting-started.md
  keep_original: true

Diagram Generation

Auto-generate visual documentation:

diagrams:
  architecture:
    type: mermaid
    source: "from imports and dependencies"
  database:
    type: erd
    source: "from model definitions"
  api_flow:
    type: sequence
    source: "from route handlers"

Integration Testing

Verify examples work:

validation:
  test_examples: true
  check_links: true
  validate_openapi: true
  require_code_coverage: 80

Frequently Asked Questions

Q: Won't auto-generated docs be generic and unhelpful?

A: The workflow extracts context from your code, comments, and existing docs. With good inline documentation and examples, generated docs are surprisingly useful. Think of it as a smart template system that adapts to your actual code.

Q: How do I handle complex explanations that need human writing?

A: Use the workflow for reference documentation (APIs, configuration, changelogs) and write narrative docs (tutorials, concepts) manually. The workflow marks sections it generates so you know what to review.

Q: Can this work with existing documentation systems?

A: Yes. The workflow outputs standard Markdown that works with MkDocs, Docusaurus, GitBook, or any static site generator. Configure the output format to match your system.

Q: What about versioned documentation?

A: Configure the workflow to generate docs for each version branch. Combine with hosting that supports versioning (ReadTheDocs, Docusaurus) for full version management.

Q: How do I prevent documentation-only changes from triggering CI?

A: Configure your CI to ignore paths:

on:
  push:
    paths-ignore:
      - 'docs/**'
      - 'README.md'

Pro Tips for Maximum Impact

  1. Start with Changelogs: They're high-value and low-risk. Get comfortable with automated changelogs before tackling API docs.

  2. Invest in Examples: The quality of generated docs depends on your examples. Maintain a robust examples/ directory.

  3. Use Conventional Commits: Standard commit messages (feat:, fix:, docs:) make changelog generation much better.

  4. Review Generated Docs: Always review before committing. The workflow is smart but not perfect.

  5. Version Your Docs: Keep docs for old versions accessible. Users don't always upgrade immediately.

  6. Link Everything: Cross-reference between docs. The workflow can help identify where links should go.

  7. Measure Usage: Track which docs are most viewed. Focus improvement efforts there.

Ready to never write documentation again? Set up the Docs Auto-Generator and watch your documentation maintain itself.