Documentation Workflow

Keep documentation synchronized with code changes using ClaudeKit’s automated documentation management.

Overview

The documentation workflow ensures your project documentation stays current, accurate, and useful as your codebase evolves.

When to Use This Workflow

  • Starting a new project
  • After completing features
  • Before releases
  • When onboarding new team members
  • Regular documentation maintenance

Step-by-Step Guide

1. Initialize Documentation

/docs:init

What happens:

  • Docs Manager Agent creates documentation structure
  • Researcher Agent analyzes existing codebase
  • Planner Agent creates documentation plan
  • Sets up documentation tooling

Output Created:

  • docs/ directory structure
  • README.md with project overview
  • API documentation template
  • Contributing guidelines
  • Code of conduct
  • Architecture documentation

2. Initial Documentation Generation

/docs:init "comprehensive project documentation"

What happens:

  • Docs Manager Agent generates initial docs
  • Researcher Agent extracts information from code
  • UI/UX Designer Agent creates diagrams and visuals
  • Copywriter Agent writes clear explanations

Documentation Generated:

  • Project overview and goals
  • Architecture diagrams
  • API documentation from code annotations
  • Setup and installation guides
  • Development workflow documentation

3. Update Documentation After Changes

/docs:update "after implementing user authentication"

What happens:

  • Docs Manager Agent identifies what needs updating
  • Researcher Agent analyzes code changes
  • Code Reviewer Agent ensures technical accuracy
  • Copywriter Agent improves clarity and readability

Updates Applied:

  • API documentation for new endpoints
  • New feature documentation
  • Updated architecture diagrams
  • Modified setup instructions
  • New examples and tutorials

4. Comprehensive Documentation Review

/docs:summarize "complete documentation review"

What happens:

  • Docs Manager Agent performs comprehensive review
  • Copywriter Agent improves writing quality
  • UI/UX Designer Agent creates missing diagrams
  • Tester Agent validates code examples

Review Coverage:

  • Consistency check across all docs
  • Accuracy verification of code examples
  • Completeness assessment
  • Readability and clarity improvements
  • Visual content enhancement

Real Example

Let’s document a new authentication feature:

Step 1: Initial Setup

/docs:init

Created Structure:

docs/
├── README.md
├── getting-started/
│   ├── installation.md
│   └── quick-start.md
├── api/
│   ├── authentication.md
│   ├── users.md
│   └── errors.md
├── architecture/
│   ├── overview.md
│   └── database-schema.md
└── development/
    ├── contributing.md
    └── testing.md

Step 2: Update After Feature

/docs:update "after implementing OAuth authentication"

Updates Made:

  • Added OAuth authentication guide
  • Updated API documentation with new endpoints
  • Modified quick-start to include auth setup
  • Created authentication architecture diagram
  • Added troubleshooting section

Step 3: Review and Improve

/docs:summarize "authentication documentation quality"

Improvements Applied:

  • Simplified complex explanations
  • Added more code examples
  • Created step-by-step tutorials
  • Improved navigation structure
  • Added FAQ section

Documentation Types

API Documentation

/docs:init "generate API documentation from code"
  • REST API endpoints
  • GraphQL schemas
  • WebSocket events
  • Request/response examples
  • Error codes and handling

User Guides

/docs:update "create user guide for new feature"
  • Step-by-step tutorials
  • Common use cases
  • Best practices
  • Troubleshooting guides
  • FAQ sections

Developer Documentation

/docs:update "development setup and workflows"
  • Local development setup
  • Code contribution guidelines
  • Testing procedures
  • Release process
  • Architecture decisions

Architecture Documentation

/docs:summarize "system architecture and design"
  • High-level architecture
  • Data flow diagrams
  • Service interactions
  • Database schemas
  • Security considerations

Advanced Documentation Workflows

Multi-language Documentation

/docs:update "create Japanese translation of user guide"
  • Automatic translation with human review
  • Cultural adaptation
  • Region-specific examples
  • Localized screenshots

Interactive Documentation

/docs:init "create interactive API documentation"
  • Try-it-now API consoles
  • Interactive tutorials
  • Live code examples
  • Embedded demos

Video Documentation

/docs:update "create video tutorials for complex features"
  • Screen recording workflows
  • Animated explanations
  • Step-by-step video guides
  • Visual concept explanations

Best Practices

Writing Quality Documentation

  1. Clear Purpose: Each document has a clear goal and audience
  2. Consistent Style: Follow established style guides
  3. Practical Examples: Include real-world code examples
  4. Regular Updates: Keep docs current with code changes
  5. User Feedback: Incorporate user suggestions and corrections

Documentation Structure

  1. Logical Organization: Group related content together
  2. Clear Navigation: Easy to find relevant information
  3. Progressive Disclosure: Start simple, add complexity gradually
  4. Cross-References: Link between related documents
  5. Search Optimization: Use clear headings and keywords

Code Examples in Documentation

  1. Working Examples: All code examples should be tested
  2. Complete Context: Show necessary imports and setup
  3. Error Handling: Include proper error handling patterns
  4. Multiple Languages: Provide examples in different languages when applicable
  5. Version Specific: Clearly indicate version compatibility

Integration with Development Workflow

Pre-commit Documentation Check

# Add to pre-commit hook
/docs:summarize "check documentation for changes"

Automated Documentation Updates

# Run after feature completion
/cook
/docs:update "document new feature"
/git:cm

Release Documentation

/docs:update "prepare release notes and documentation"
/docs:summarize "final review before release"

Measuring Documentation Quality

Metrics to Track

  • Documentation coverage percentage
  • User feedback scores
  • Time to find information
  • Number of support tickets reduced
  • Developer onboarding time

Quality Assessment

/docs:summarize "comprehensive documentation quality assessment"
  • Completeness analysis
  • Accuracy verification
  • Readability scoring
  • User experience evaluation
  • Maintenance requirements

Tools and Integration

Documentation Platforms

  • GitBook for user-facing docs
  • Notion for internal knowledge base
  • GitHub Pages for static sites
  • Confluence for team documentation
  • Docusaurus for React-based docs

Automation

  • GitHub Actions for doc builds
  • Automated API docs generation
  • Link checking workflows
  • Spell checking and grammar
  • Screenshot automation

Getting Help