Documentation

This skill provides comprehensive documentation capabilities including API documentation, technical writing, changelog generation, and developer guides. It covers everything from OpenAPI specifications to user-facing changelogs.

When to Use This Skill

When documenting REST APIs or GraphQL schemas
When creating OpenAPI/Swagger specifications
When generating client SDKs
When writing API integration guides
When creating interactive API documentation
When maintaining API versioning and migration guides
When writing user guides and tutorials
When creating or improving README files
When documenting architecture and design decisions
When writing code comments and inline documentation
When improving content clarity and accessibility
When creating getting started documentation
When writing feature specifications and design documents
When creating Architecture Decision Records (ADRs)
When documenting technical decisions and their rationale
When creating migration guides for version upgrades
When documenting breaking changes and upgrade paths
When planning and documenting database migrations
When preparing release notes for a new version
When creating weekly or monthly product update summaries
When documenting changes for customers
When writing changelog entries for app store submissions
When generating update notifications
When creating internal release documentation
When maintaining a public changelog/product updates page

What This Skill Does

OpenAPI Specs: Creates complete OpenAPI 3.0/Swagger specifications
SDK Generation: Generates client libraries and SDKs
Interactive Docs: Creates Postman collections and interactive docs
Versioning: Manages API versioning and migration guides
Code Examples: Provides examples in multiple languages
Developer Guides: Writes authentication and integration guides
User Guides: Creates step-by-step user guides with clear instructions
Tutorials: Writes progressive tutorials that build knowledge
README Files: Creates comprehensive README files with badges and sections
Architecture Docs: Documents system architecture and design decisions
Code Documentation: Writes clear code comments and inline docs
Content Organization: Structures content with clear headings and flow
Changelog Generation: Transforms git commits into user-friendly changelogs
Design Specs: Creates feature specifications and technical design documents
ADRs: Documents Architecture Decision Records with context and consequences
Migration Guides: Creates step-by-step migration documentation with rollback procedures

How to Use

Document API

Create OpenAPI specification for this API

Generate API documentation for the /api/users endpoints

Write Documentation

Create a user guide for this feature

Write a README for this project

Generate Changelog

Create a changelog from commits since last release

Generate changelog for all commits from the past week

API Documentation

Document as You Build

Document APIs during development, not after
Keep documentation in sync with code
Use real examples over abstract descriptions
Show both success and error cases
Version everything including docs

OpenAPI Specification

Structure:

API metadata (title, version, description)
Server definitions
Security schemes
Paths and operations
Request/response schemas
Examples for all operations

Example:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

SDK Generation

Supported Languages:

JavaScript/TypeScript
Python
Java
Go
Ruby
PHP

Tools:

OpenAPI Generator
Swagger Codegen
SDK generators

Code Examples

Provide examples in multiple languages:

JavaScript/Node.js
Python
cURL
Ruby
Java

Technical Writing

Write for Your Audience

Know their skill level
Use appropriate terminology
Provide context when needed
Assume minimal prior knowledge
Include troubleshooting sections

Lead with the Outcome

Start with what users will accomplish
Show the value before the steps
Use clear, action-oriented language
Focus on user success, not features

Use Active Voice

Prefer active over passive voice
Use clear, concise language
Avoid jargon when possible
Include real examples and scenarios
Test instructions by following them exactly

Documentation Types

User Guides:

Overview and goals
Prerequisites
Step-by-step instructions
Screenshots or examples
Troubleshooting
Next steps

README Files:

Project title and description
Badges (build status, version, license)
Features
Installation
Quick start
Usage examples
Contributing
License

Architecture Docs:

System overview
Component diagrams
Design decisions
Technology choices
Integration points
Data flow

Changelog Generation

Transforming Git Commits

Automatically creates user-facing changelogs from git commits by:

Analyzing commit history
Categorizing changes (features, improvements, bug fixes, breaking changes, security)
Transforming technical commits into clear, customer-friendly release notes
Filtering out internal commits (refactoring, tests, etc.)

Basic Usage

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

With Specific Date Range

Create a changelog for all commits between March 1 and March 15

With Custom Guidelines

Create a changelog for commits since v2.4.0, using my changelog
guidelines from CHANGELOG_STYLE.md

Example Output

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

Reference Files

For detailed documentation patterns and guidance, load reference files as needed:

references/api_docs.md - API documentation patterns, OpenAPI specifications, SDK generation, versioning strategies, and code examples
references/technical_writing.md - Technical writing best practices, user guide structure, README templates, architecture documentation, and content organization
references/changelogs.md - Changelog generation patterns, commit categorization, user-friendly transformation, and release note best practices
references/API_DOCUMENTATION.template.md - REST API documentation template with endpoints, authentication, webhooks, and SDK examples
references/CHANGELOG.template.md - Changelog template following Keep a Changelog format with SemVer
references/DESIGN_SPEC.template.md - Design specification template for feature planning, technical design, and implementation approach
references/ARCHITECTURE_DECISION_RECORD.template.md - ADR template for documenting significant architectural decisions with context and consequences
references/MIGRATION_GUIDE.template.md - Migration guide template for version upgrades, breaking changes, and upgrade paths

When working on specific documentation types, load the appropriate reference file.

Best Practices

Documentation Quality

Real Examples: Use actual working examples, not placeholders
Error Cases: Document error responses with examples
Authentication: Clear authentication setup instructions
Versioning: Document versioning strategy and migration paths
Testing: Test all examples to ensure they work

Developer Experience

Quick Start: Provide 5-minute quick start guide
Interactive: Use tools like Postman or Swagger UI
Searchable: Make documentation searchable
Up-to-Date: Keep documentation current with API changes
Feedback: Include ways for developers to provide feedback

Writing Guidelines

Clarity: Use simple, clear language
Structure: Organize with clear headings
Examples: Include real, working examples
Testing: Test all instructions yourself
Feedback: Include ways for users to provide feedback

Content Organization

Hierarchy: Use clear heading structure
Navigation: Include table of contents for long docs
Search: Make content searchable
Cross-references: Link related sections
Updates: Keep documentation current

Accessibility

Plain Language: Avoid unnecessary jargon
Structure: Use semantic HTML/Markdown
Images: Include alt text for images
Formatting: Use consistent formatting
Examples: Provide multiple examples for different skill levels

Changelog Best Practices

Run from git repository root
Specify date ranges for focused changelogs
Use CHANGELOG_STYLE.md for consistent formatting
Review and adjust the generated changelog before publishing
Save output directly to CHANGELOG.md

Related Use Cases

API specification creation
SDK generation
Developer onboarding
API integration guides
Version migration documentation
Interactive API exploration
User documentation
Developer guides
Architecture documentation
Tutorial creation
Content improvement
Creating GitHub release notes
Writing app store update descriptions
Generating email updates for users
Creating social media announcement posts