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