Documentation Generation

Generate comprehensive technical documentation across multiple layers: API documentation, code documentation, documentation sites, architecture decisions, and system diagrams.

When to Use This Skill

Use this skill when:

• Documenting REST or GraphQL APIs with OpenAPI specifications
• Creating code documentation for libraries (TypeScript, Python, Go, Rust)
• Building documentation sites for projects or products
• Recording architectural decisions (ADRs) for system design choices
• Generating diagrams to visualize system architecture or data flows
• Setting up automated documentation pipelines in CI/CD

Documentation Layers Overview

Technical documentation operates at five distinct layers:

Layer 1: API Documentation - OpenAPI specs for REST/GraphQL APIs (Swagger UI, Redoc, Scalar) Layer 2: Code Documentation - Generated from code comments (TypeDoc, Sphinx, godoc, rustdoc) Layer 3: Documentation Sites - Comprehensive guides and tutorials (Docusaurus, MkDocs) Layer 4: Architecture Decisions - ADRs using MADR template format Layer 5: Diagrams - Visual architecture (Mermaid, PlantUML, D2)

See references/api-documentation.md, references/code-documentation.md, and references/documentation-sites.md for detailed guides.

Quick Decision Framework

Which Documentation Layer?

API for external consumers?
  → Layer 1: API Documentation (OpenAPI + Swagger UI/Redoc)

Code for maintainers?
  → Layer 2: Code Documentation (TypeDoc/Sphinx/godoc/rustdoc)

Comprehensive guides?
  → Layer 3: Documentation Site (Docusaurus/MkDocs)

Architectural decision?
  → Layer 4: ADR (MADR template)

Visual system design?
  → Layer 5: Diagrams (Mermaid/PlantUML/D2)

Tool Selection Matrix