generating-documentation_skill

Overview

This skill generates comprehensive technical documentation across APIs, codebases, documentation sites, architecture decisions, and diagrams. It produces OpenAPI/Swagger specs, TypeDoc/Sphinx outputs, Docusaurus/MkDocs sites, MADR-style ADRs, and Mermaid/PlantUML diagrams to make developer-facing documentation consistent and maintainable.

How this skill works

Provide source code, API contracts, or architecture notes and the skill will generate specs, docsite scaffolding, code docs, ADR templates, and diagram markup. It can produce starter OpenAPI YAML, TSDoc/TypeDoc or Sphinx-compatible docstrings, Docusaurus/MkDocs configs, MADR ADR files, and Mermaid/PlantUML diagrams, plus CI steps to validate and publish artifacts.

When to use it

• Publishing REST or GraphQL API docs for external or internal consumers
• Creating library or SDK reference docs from TypeScript, Python, Go, or Rust code
• Building a centralized documentation site for product or developer docs
• Capturing architecture decisions using ADR templates for team alignment
• Generating architecture and flow diagrams to visualize systems
• Automating docs generation and deployment in CI/CD pipelines

Best practices

• Adopt docs-as-code: keep docs and templates in version control
• Choose design-first for new public APIs and code-first for existing services
• Generate a single source of truth (OpenAPI or inline docstrings) and derive outputs
• Automate generation, linting, and validation in CI to prevent drift
• Include runnable examples and snippets for every API and public function
• Version docs alongside releases and maintain clear navigation

Example use cases

• Create an OpenAPI spec and render it with Swagger UI for interactive testing
• Generate TypeDoc for a TypeScript UI library and publish via Docusaurus
• Add Sphinx docstrings to a Python package and build HTML docs automatically
• Record a database selection decision as a MADR ADR with pros/cons and outcome
• Produce Mermaid diagrams for sequence flows and embed them in docs
• Implement a GitHub Actions workflow to build, validate, and deploy docs-site