documentation-generation_skill

Overview

This skill generates clear, maintainable technical documentation for codebases and services. It produces API docs, component libraries, README files, architecture diagrams, changelogs, and developer guides using tools like OpenAPI/Swagger, JSDoc/TypeDoc, Storybook, VitePress, and Docusaurus. The output is versioned, testable, and designed to be a single source of truth for developers and stakeholders. It focuses on practical examples, automated checks, and audience-specific content.

How this skill works

I extract structured metadata from code (comments, schemas, and types) and generate human-friendly documentation pages and spec files. I can scaffold README templates, produce OpenAPI/Swagger specs for REST, generate GraphQL schema docs, create Storybook component stories, and assemble static sites with Docusaurus or VitePress. I add CI checks for broken links and runnable code examples to keep docs fresh and reliable. Diagrams and ADRs are created or formatted to document architecture and decisions.

When to use it

• Documenting REST or GraphQL APIs for internal or public consumption
• Creating or maintaining a component library with Storybook
• Writing or updating README, onboarding, or configuration guides
• Generating API reference sites using OpenAPI, TypeDoc, or JSDoc
• Creating architecture diagrams, ADRs, changelogs, and migration guides

Best practices

• Treat docs as code: keep docs in version control and review changes via PRs
• Prefer generated single-source-of-truth from code and schema comments
• Include runnable examples and test them in CI to prevent rot
• Tailor content by audience: public API docs, developer guides, and ops runbooks
• Automate link checks, example execution, and versioned site builds

Example use cases

• Auto-generate OpenAPI docs from annotated routes and serve Swagger UI at /api-docs
• Build a Docusaurus site with guides, API reference, and a searchable sidebar
• Create Storybook stories and component docs for a design system
• Write a README + CHANGELOG with semantic versioning and migration notes
• Extract and test code examples from documentation during CI to ensure accuracy