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