documentation-builder

name	Documentation Builder
description	Generates professional API documentation, user guides, and architectural documentation from code and specifications.

Documentation Builder Skill

Overview

The Documentation Builder Skill transforms your codebase and specifications into professional, well-structured documentation. It analyzes your code, APIs, and architecture, then generates:

• API Documentation - OpenAPI-style reference with authentication, endpoints, errors
• User Guides - Getting started, tutorials, how-tos
• Architecture Documentation - System design, data flows, component relationships
• Setup Guides - Installation, configuration, deployment instructions

When to use this skill:

• Starting a new project and need documentation foundation
• Updating documentation to match code changes
• Converting code into professional API reference
• Creating user onboarding materials
• Generating architectural documentation

Quick Start

Tell the Documentation Builder what you need:

"Create API documentation for our REST endpoints including:
- Authentication (JWT)
- All CRUD operations
- Error responses
- Rate limiting info
- Code examples in Python and JavaScript"

The skill analyzes your code and generates:

1. Structured markdown documentation
2. Code examples in requested languages
3. Table of contents and navigation
4. Diagrams (if complexity warrants)

Documentation Types

API Documentation

Generated sections:

• Overview and base URL
• Authentication methods (OAuth, JWT, API Key)
• Available endpoints (organized by resource)
• Request/response schemas
• Error codes and messages
• Rate limits
• Code examples (Python, JavaScript, cURL)
• WebSocket/real-time info (if applicable)

Quality standards:

• ✅ All endpoints documented
• ✅ All parameters explained
• ✅ All error codes covered
• ✅ Multiple code examples per endpoint
• ✅ Common workflows documented

Output formats:

• Markdown (for GitHub, GitBook)
• OpenAPI/Swagger (for tooling)
• HTML (for hosting)
• PDF (for distribution)

User Guides

Typical sections:

1. Getting Started

   • Installation/setup
   • First run/quick tutorial
   • Common first tasks

2. Core Concepts

   • Architecture overview
   • Key terminology
   • Mental models

3. How-To Guides

   • Authentication setup
   • Common workflows
   • Troubleshooting
   • Best practices

4. Advanced Topics

   • Configuration options
   • Performance tuning
   • Customization
   • Extending functionality

5. Reference

   • Configuration reference
   • Environment variables
   • Command reference
   • API reference (if applicable)

Architecture Documentation

Typically includes:

• System overview diagram
• Component relationships
• Data flow diagrams
• Deployment architecture
• Technology stack
• Database schema (if applicable)
• Security considerations
• Scalability approach
• Disaster recovery plan

Quality standards:

• ✅ Clear system boundaries
• ✅ Component responsibilities documented
• ✅ Data flow clear and accurate
• ✅ Technology choices explained
• ✅ Future scalability addressed

Usage Examples

Example 1: API Documentation

Input:
"Generate API documentation for our Flask REST API with:
- 8 endpoints (CRUD on two resources)
- JWT authentication
- JSON request/response
- Error handling
- Include Python and JavaScript examples"

Process:
1. Analyze Flask route definitions
2. Extract endpoint signatures
3. Parse request/response validation
4. Generate OpenAPI spec
5. Create markdown with examples
6. Format for multiple platforms

Output:
- api-documentation.md (complete reference)
- openapi.json (machine-readable spec)
- api-docs.html (hosted version)
- api-docs.pdf (downloadable version)

Example 2: Getting Started Guide

Input:
"Create a 'Getting Started' guide for developers setting up
our development environment"

Process:
1. Analyze setup scripts and configuration
2. Identify prerequisites and dependencies
3. Document installation steps
4. Create first-run tutorial
5. Add common gotchas and solutions
6. Include troubleshooting section

Output:
- getting-started.md
- Inline code examples
- Screenshots/diagrams
- Video tutorial outline

Example 3: Architecture Documentation

Input:
"Document our microservices architecture including:
- 5 services
- Kafka message queue
- PostgreSQL database
- Redis cache
- Load balancing approach"

Process:
1. Analyze service definitions
2. Map service boundaries
3. Document data flows
4. Create architecture diagram
5. Explain technology choices
6. Document deployment approach
7. Plan for scalability

Output:
- architecture.md (comprehensive overview)
- service-diagram.png (visual representation)
- data-flow.png (data pipeline)
- deployment.md (deployment guide)

Advanced Features

Multi-Format Output

Generate documentation in multiple formats simultaneously:

• Markdown - Git-friendly, searchable
• OpenAPI/Swagger - Automated tooling
• HTML - Web hosting
• PDF - Downloadable/offline
• Docusaurus - Site generation ready
• MkDocs - Wiki generation ready

Language-Specific Examples

Auto-generate code examples in multiple languages:

• Python
• JavaScript/TypeScript
• Java
• Go
• C#
• Ruby
• cURL/Bash

Automatic Diagram Generation

Creates diagrams for complex systems:

• Architecture diagrams
• Data flow diagrams
• Entity relationship diagrams
• Deployment topology diagrams
• Sequence diagrams (for workflows)

Maintenance Documentation

Keeps documentation in sync:

• Update signatures as code changes
• Regenerate examples
• Version documentation
• Create changelogs

Best Practices

1. Clear Specifications

Provide context so skill understands your system:

"Create API docs for our payment processing endpoint
that uses Stripe, includes webhook handling, and PCI compliance notes"

Instead of:

"Document the payment API"

2. Code Examples Matter

Specify what examples would be most useful:

"Include examples showing:
- Successful payment processing flow
- Handling failed payments
- Setting up webhook handlers
- Common error scenarios"

3. Audience Awareness

Tell the skill who will read the docs:

"Write for mid-level Python developers who know requests
but may be new to async patterns"

4. Format for Purpose

Different docs serve different purposes:

• API Docs: For developers integrating your service
• User Guides: For end users
• Architecture: For team maintenance
• Deployment: For operations teams

5. Keep Current

Regenerate when significant changes occur:

• New endpoints or features
• Changed authentication approach
• Updated architecture
• Performance optimizations

Customization Options

Code Example Languages

Specify which languages to include:

{
  "example_languages": ["python", "javascript", "typescript"],
  "include_curl": true,
  "include_postman": true
}

Documentation Sections

Choose which sections to include:

{
  "sections": [
    "overview",
    "authentication",
    "endpoints",
    "errors",
    "examples",
    "webhooks",
    "rate_limiting"
  ]
}

Styling & Branding

Customize appearance:

{
  "brand": {
    "company_name": "MyCompany",
    "logo_url": "https://...",
    "primary_color": "#007AFF"
  }
}

Output Targets

Specify destination formats:

{
  "outputs": [
    "markdown",
    "openapi.json",
    "html",
    "pdf",
    "docusaurus"
  ]
}

Integration Points

With Version Control

• Commit documentation updates
• Track documentation changes
• Maintain doc history
• Create documentation branches

With CI/CD

• Generate docs on every commit
• Validate documentation accuracy
• Publish to GitHub Pages
• Create doc versioning

With API Platforms

• Export to API Marketplaces
• Sync with API gateways
• Update API management tools
• Generate SDKs from docs

Performance Considerations

• Small API (5-10 endpoints): 2-3 minutes
• Medium API (20-50 endpoints): 5-10 minutes
• Large System (complex architecture): 15-20 minutes

Estimated tokens:

• API documentation: 8K-12K
• User guide: 10K-15K
• Architecture docs: 12K-18K
• Combined full suite: 20K-30K

Quality Checklist

✅ Documentation is complete when:

• All public APIs documented
• All parameters explained
• All error codes covered
• Examples are accurate and runnable
• Formatting is consistent
• Navigation is clear
• Search works (if applicable)
• Mobile-friendly (if web-based)
• Up-to-date with current code
• Includes troubleshooting guide

Troubleshooting

Missing Endpoints

Cause: Code structure not analyzed properly Solution: Provide explicit endpoint list

Unclear Examples

Cause: Context not specific enough Solution: Provide actual code or detailed descriptions

Formatting Issues

Cause: Complex markdown structure Solution: Specify desired output format (Markdown, HTML, etc.)

---

For technical implementation details, see REFERENCE.md