generating-documentation

# 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

| Need | Primary Tool | Best For |
|------|-------------|----------|
| **Doc Site** | Docusaurus | Feature-rich React sites |
| **Doc Site** | MkDocs Material | Simple Python docs |
| **API Docs (Interactive)** | Swagger UI | Testin