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