Documentation

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

1. OpenAPI Specs: Creates complete OpenAPI 3.0/Swagger specifications 2. SDK Generation: Generates client libraries and SDKs 3. Interactive Docs: Creates Postman collections and interactive docs 4. Versioning: Manages API versioning and migration guides 5. Code Examples: Provides examples in multiple languages 6. Developer Guides: Writes authentication and integration guides 7. User Guides: Creates step-by-step user guides with clear instructions 8. Tutorials: Writes progressive tutorials that build knowledge 9. README Files: Creates comprehensive README files with badges and sections 10. Architecture Docs: Documents system architecture and design decisions 11. Code Documentation: Writes clear code comments and inline docs 12. Content Organization: Structures content with clear headings and flow 13. Changelog Generation: Transforms git commits into user-friendly changelogs 14. Design Specs: Creates feature specifications and technical design documents 15. ADRs: Documents Architecture Decision Records with context and consequences 16. 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

1. Real Examples: Use actual working examples, not placeholders 2. Error Cases: Document error responses with examples 3. Authentication: Clear authentication setup instructions 4. Versioning: Document versioning strategy and migration paths 5. 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

1. Clarity: Use simple, clear language 2. Structure: Organize with clear headings 3. Examples: Include real, working examples 4. Testing: Test all instructions yourself 5. 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

API Documentation

Comprehensive guide for creating API documentation, OpenAPI specifications, SDKs, and developer guides.

OpenAPI Specification

Structure

Required Sections:

• openapi: Version (3.0.0)
• info: API metadata
• paths: API endpoints
• components: Reusable schemas and parameters

Optional Sections:

• servers: Server definitions
• security: Security schemes
• tags: Endpoint grouping
• externalDocs: External documentation links

Complete Example

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: RESTful API for user management
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /users:
    get:
      summary: List all users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              example1:
                value:
                  email: user@example.com
                  name: John Doe
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
      required:
        - email
        - name

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

SDK Generation

Using OpenAPI Generator

JavaScript/TypeScript:

npx @openapitools/openapi-generator-cli generate \
  -i api.yaml \
  -g typescript-axios \
  -o ./sdk/typescript

Python:

npx @openapitools/openapi-generator-cli generate \
  -i api.yaml \
  -g python \
  -o ./sdk/python

Java:

npx @openapitools/openapi-generator-cli generate \
  -i api.yaml \
  -g java \
  -o ./sdk/java

SDK Structure

TypeScript SDK Example:

import { Configuration, UsersApi } from './sdk';

const config = new Configuration({
  basePath: 'https://api.example.com/v1',
  accessToken: 'your-token',
});

const api = new UsersApi(config);

// Create user
const user = await api.createUser({
  email: 'user@example.com',
  name: 'John Doe',
});

// List users
const users = await api.listUsers({ page: 1, limit: 20 });

Code Examples

JavaScript/Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.example.com/v1',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

// Create user
const user = await client.post('/users', {
  email: 'user@example.com',
  name: 'John Doe'
});

// Get user
const userData = await client.get(`/users/${user.data.id}`);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Create user
response = requests.post(
    'https://api.example.com/v1/users',
    json={'email': 'user@example.com', 'name': 'John Doe'},
    headers=headers
)

# Get user
user = requests.get(
    f'https://api.example.com/v1/users/{response.json()["id"]}',
    headers=headers
)

cURL

# Create user
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"John Doe"}'

# Get user
curl https://api.example.com/v1/users/USER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Versioning

API Versioning Strategies

URL Versioning:

/api/v1/users
/api/v2/users

Header Versioning:

Accept: application/vnd.example.v1+json

Query Parameter:

/api/users?version=1

Migration Guides

Structure:

• Overview of changes
• Breaking changes list
• Migration steps
• Code examples (before/after)
• Deprecation timeline

Interactive Documentation

Swagger UI

Setup:

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./api.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Postman Collections

Export from OpenAPI:

npx openapi-to-postman -s api.yaml -o postman-collection.json

Best Practices

Documentation Standards

1. Complete Examples: Every endpoint should have request/response examples 2. Error Documentation: Document all possible error responses 3. Authentication: Clear authentication instructions 4. Rate Limiting: Document rate limits and quotas 5. Pagination: Explain pagination parameters

Developer Experience

• Quick Start: 5-minute getting started guide
• Try It Out: Interactive API explorer
• SDKs: Provide SDKs for common languages
• Changelog: Document API changes
• Support: Provide support channels

{{API_NAME}} API Documentation

Version: {{VERSION}} Base URL: {{BASE_URL}} Last Updated: {{DATE}}

---

Overview

{{API_DESCRIPTION}}

Authentication

Authorization: Bearer {{TOKEN}}

Rate Limiting

Headers:

• X-RateLimit-Limit: Maximum requests
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

---

Endpoints

{{RESOURCE_NAME}}

List {{RESOURCES}}

GET /{{RESOURCE}}

Query Parameters:

Response:

{
  "data": [
    {
      "id": "{{ID}}",
      "{{FIELD}}": "{{VALUE}}"
    }
  ],
  "meta": {
    "total": {{N}},
    "limit": {{N}},
    "offset": {{N}}
  }
}

Get {{RESOURCE}}

GET /{{RESOURCE}}/{{id}}

Path Parameters:

Response: 200 OK

{
  "id": "{{ID}}",
  "{{FIELD}}": "{{VALUE}}",
  "created_at": "{{ISO_DATE}}",
  "updated_at": "{{ISO_DATE}}"
}

Create {{RESOURCE}}

POST /{{RESOURCE}}

Request Body:

{
  "{{FIELD}}": "{{VALUE}}",
  "{{FIELD}}": {{VALUE}}
}

Response: 201 Created

Update {{RESOURCE}}

PATCH /{{RESOURCE}}/{{id}}

Request Body:

{
  "{{FIELD}}": "{{NEW_VALUE}}"
}

Response: 200 OK

Delete {{RESOURCE}}

DELETE /{{RESOURCE}}/{{id}}

Response: 204 No Content

---

Error Handling

Error Response Format

{
  "error": {
    "code": "{{ERROR_CODE}}",
    "message": "{{ERROR_MESSAGE}}",
    "details": [
      {
        "field": "{{FIELD}}",
        "issue": "{{ISSUE}}"
      }
    ]
  }
}

Error Codes

---

Webhooks

Event Types

Payload Format

{
  "event": "{{EVENT_TYPE}}",
  "timestamp": "{{ISO_DATE}}",
  "data": {
    "{{RESOURCE}}": { ... }
  }
}

Signature Verification

X-Webhook-Signature: sha256={{SIGNATURE}}

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

---

SDKs

JavaScript/TypeScript

npm install {{PACKAGE_NAME}}

import { Client } from '{{PACKAGE_NAME}}';

const client = new Client({ apiKey: '{{API_KEY}}' });
const items = await client.{{resource}}.list();

Python

pip install {{PACKAGE_NAME}}

from {{package_name}} import Client

client = Client(api_key="{{API_KEY}}")
items = client.{{resource}}.list()

---

Examples

cURL

curl -X GET "{{BASE_URL}}/{{RESOURCE}}" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json"

Create Resource

curl -X POST "{{BASE_URL}}/{{RESOURCE}}" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"{{FIELD}}": "{{VALUE}}"}'

---

Changelog

v{{VERSION}} ({{DATE}})

• Added: {{NEW_ENDPOINT}}
• Changed: {{MODIFIED_BEHAVIOR}}
• Deprecated: {{DEPRECATED_FIELD}}
• Removed: {{REMOVED_ENDPOINT}}

---

Quality Checklist

• [ ] All endpoints documented
• [ ] Request/response examples provided
• [ ] Error codes comprehensive
• [ ] Authentication methods explained
• [ ] Rate limits documented
• [ ] SDK examples included
• [ ] Webhook payloads documented

ADR-{{NUMBER}}: {{TITLE}}

Status: {{PROPOSED|ACCEPTED|DEPRECATED|SUPERSEDED}} Date: {{YYYY-MM-DD}} Deciders: {{NAMES}} Technical Story: {{TICKET_OR_ISSUE}}

---

Context

{{DESCRIPTION_OF_CONTEXT}}

Problem Statement

{{SPECIFIC_PROBLEM_TO_SOLVE}}

Constraints

• {{CONSTRAINT_1}}
• {{CONSTRAINT_2}}

Assumptions

• {{ASSUMPTION_1}}
• {{ASSUMPTION_2}}

---

Decision Drivers

• {{DRIVER_1}}
• {{DRIVER_2}}
• {{DRIVER_3}}

---

Considered Options

Option 1: {{OPTION_NAME}}

{{DESCRIPTION}}

Pros:

• {{PRO_1}}
• {{PRO_2}}

Cons:

• {{CON_1}}
• {{CON_2}}

Option 2: {{OPTION_NAME}}

{{DESCRIPTION}}

Pros:

• {{PRO_1}}
• {{PRO_2}}

Cons:

• {{CON_1}}
• {{CON_2}}

Option 3: {{OPTION_NAME}}

{{DESCRIPTION}}

Pros:

• {{PRO_1}}
• {{PRO_2}}

Cons:

• {{CON_1}}
• {{CON_2}}

---

Decision Outcome

Chosen Option: {{OPTION_NAME}}

Rationale

{{WHY_THIS_OPTION_WAS_CHOSEN}}

Expected Consequences

Positive:

• {{POSITIVE_1}}
• {{POSITIVE_2}}

Negative:

• {{NEGATIVE_1}}
• {{NEGATIVE_2}}

Risks:

• {{RISK_1}}: Mitigation: {{MITIGATION}}

---

Implementation

Action Items

• [ ] {{ACTION_1}}
• [ ] {{ACTION_2}}
• [ ] {{ACTION_3}}

Affected Components

Migration Path

{{MIGRATION_STEPS_IF_APPLICABLE}}

---

Validation

Success Criteria

• [ ] {{CRITERION_1}}
• [ ] {{CRITERION_2}}

Metrics to Track

---

Related Decisions

• ADR-{{N}}: {{RELATED_TITLE}}
• ADR-{{N}}: {{RELATED_TITLE}}

Supersedes

• ADR-{{N}}: {{SUPERSEDED_TITLE}} (if applicable)

---

References

• {{LINK_OR_DOCUMENT}}
• {{LINK_OR_DOCUMENT}}

---

Quality Checklist

• [ ] Context clearly explains the situation
• [ ] All viable options were considered
• [ ] Decision drivers are explicit
• [ ] Consequences (positive and negative) documented
• [ ] Implementation path defined
• [ ] Success criteria measurable

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

[Unreleased]

Added

• {{NEW_FEATURE_DESCRIPTION}}

Changed

• {{CHANGED_BEHAVIOR_DESCRIPTION}}

Deprecated

• {{DEPRECATED_FEATURE_DESCRIPTION}}

Removed

• {{REMOVED_FEATURE_DESCRIPTION}}

Fixed

• {{BUG_FIX_DESCRIPTION}}

Security

• {{SECURITY_FIX_DESCRIPTION}}

---

[{{VERSION}}] - {{YYYY-MM-DD}}

Added

• New feature X that enables users to {{BENEFIT}} (#{{ISSUE}})
• Support for {{NEW_CAPABILITY}}

Changed

• Improved performance of {{COMPONENT}} by {{PERCENTAGE}}%
• Updated {{DEPENDENCY}} from {{OLD_VERSION}} to {{NEW_VERSION}}

Deprecated

• {{OLD_API}} is deprecated, use {{NEW_API}} instead

Removed

• Removed deprecated {{FEATURE}} (deprecated in {{VERSION}})

Fixed

• Fixed issue where {{BUG_DESCRIPTION}} (#{{ISSUE}})
• Resolved crash when {{SCENARIO}}

Security

• Fixed {{CVE_ID}}: {{VULNERABILITY_DESCRIPTION}}

---

[{{VERSION}}] - {{YYYY-MM-DD}}

Added

• {{FEATURE_1}}
• {{FEATURE_2}}

Changed

• {{CHANGE_1}}

Fixed

• {{FIX_1}}
• {{FIX_2}}

---

Entry Guidelines

Types of Changes

Writing Good Entries

Do:

• Start with a verb (Added, Changed, Fixed)
• Include issue/PR references
• Explain user impact
• Group related changes

Don't:

• Include internal refactoring
• Use technical jargon without explanation
• Leave entries vague

Examples

### Added

- Added export to CSV functionality for reports ([#123](url))
- Added keyboard shortcuts for common actions (Ctrl+S to save)

### Fixed

- Fixed memory leak when processing large files ([#456](url))
- Fixed incorrect timezone display for international users

---

Version Links

[Unreleased]: {{REPO_URL}}/compare/v{{LATEST}}...HEAD [{{VERSION}}]: {{REPO_URL}}/compare/v{{PREVIOUS}}...v{{VERSION}}

---

Quality Checklist

• [ ] All user-facing changes documented
• [ ] Breaking changes highlighted
• [ ] Issue/PR numbers linked
• [ ] Version number follows SemVer
• [ ] Date in ISO format (YYYY-MM-DD)
• [ ] Entries grouped by type
• [ ] Security fixes prominently noted

Changelog Generation

Guide for creating user-facing changelogs from git commits, categorizing changes, and writing clear release notes.

Changelog Generation Process

1. Analyze Git History

Scan commits from:

• Specific time period
• Between versions/tags
• Since last release
• Custom date range

Extract:

• Commit messages
• Commit authors
• Commit dates
• Changed files
• Commit types (feat, fix, etc.)

2. Categorize Changes

Categories:

• Features: New functionality
• Improvements: Enhancements to existing features
• Bug Fixes: Bug fixes and corrections
• Breaking Changes: Changes that break compatibility
• Security: Security updates
• Deprecations: Deprecated features
• Documentation: Documentation updates
• Internal: Refactoring, tests, CI/CD (usually excluded)

3. Transform Technical → User-Friendly

Technical Commit:

fix: resolve null pointer exception in user service

User-Friendly:

Fixed issue where user profiles would fail to load

Transformation Rules:

• Remove technical jargon
• Focus on user impact
• Use clear, action-oriented language
• Explain what users will notice
• Group related changes

4. Format Professionally

Structure:

• Clear sections with emojis/icons
• Grouped by category
• Chronological or by importance
• Include dates/version numbers
• Link to related issues/PRs

Changelog Format

Standard Format

# Changelog

## [Version] - YYYY-MM-DD

### ✨ Added
- New feature descriptions

### 🔧 Changed
- Changes to existing features

### 🐛 Fixed
- Bug fixes

### 🔒 Security
- Security updates

### ⚠️ Breaking Changes
- Breaking changes with migration notes

### 📝 Deprecated
- Deprecated features

### 🗑️ Removed
- Removed features

Example: Weekly Changelog

# 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
- **Improved Notifications**: Notifications are now grouped and easier to manage

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count
- Fixed crash when opening settings on mobile devices

## 🔒 Security

- Updated dependencies to address security vulnerabilities
- Improved password validation requirements

Example: Version Release Notes

# Release Notes - Version 2.5.0

**Release Date**: March 15, 2024

## What's New

### Team Collaboration Features

We've added powerful new collaboration features to help teams work together more effectively.

- **Team Workspaces**: Organize your work into separate workspaces for different projects or teams
- **Real-time Collaboration**: See team members' cursors and edits in real-time
- **Comments & Mentions**: Leave comments and mention team members to get their attention

### Performance Improvements

This release includes significant performance improvements:

- **2x Faster Sync**: Files now sync twice as fast across all your devices
- **Improved Search**: Search now includes file contents, making it easier to find what you need
- **Faster Load Times**: Pages load 30% faster on average

## Improvements

- Better notification grouping and management
- Improved mobile experience
- Enhanced keyboard shortcuts (press ? to see all)

## Bug Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count
- Fixed crash when opening settings on mobile devices

## Breaking Changes

### API Changes

The `/api/v2/users` endpoint now requires authentication for all requests.
Previously, some read operations were public.

**Migration**: Add `Authorization: Bearer <token>` header to all API requests.

## Deprecated

- The legacy import format will be removed in version 3.0. Please migrate to the new format by June 1, 2024.

## Security

- Updated dependencies to address security vulnerabilities
- Improved password validation requirements
- Enhanced encryption for sensitive data

---

**Full Changelog**: [View all commits](https://github.com/example/repo/compare/v2.4.0...v2.5.0)

Commit Message Analysis

Conventional Commits Format

Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Code style (formatting)
• refactor: Code refactoring
• perf: Performance improvement
• test: Adding tests
• chore: Maintenance tasks

Categorization Rules

Features:

• Commits with feat: type
• New functionality additions
• User-visible new capabilities

Improvements:

• Commits with perf: type
• Enhancements to existing features
• Performance optimizations
• UX improvements

Bug Fixes:

• Commits with fix: type
• Bug corrections
• Error handling improvements

Breaking Changes:

• Commits with ! in type (e.g., feat!:)
• Footer with BREAKING CHANGE:
• API changes
• Configuration changes

Security:

• Security-related commits
• Vulnerability fixes
• Security enhancements

Filtering and Exclusion

Exclude Internal Commits

Patterns to Exclude:

• refactor: (unless significant)
• test: (unless test framework changes)
• chore: (unless user-visible)
• style: (formatting only)
• ci: (CI/CD changes)
• build: (build system changes)

Include User-Visible Changes

Always Include:

• feat: (new features)
• fix: (bug fixes)
• perf: (performance improvements)
• Breaking changes
• Security updates

Best Practices

Writing User-Friendly Changelogs

1. Focus on Impact: What users will notice 2. Remove Jargon: Avoid technical terms 3. Be Specific: Clear, concrete descriptions 4. Group Related: Group similar changes 5. Prioritize: Most important changes first

Changelog Maintenance

• Regular Updates: Update weekly or monthly
• Version Tags: Tag releases in git
• Consistent Format: Use consistent structure
• Review Before Publishing: Review for clarity
• Link to Details: Link to full commit history

Tips

• Run from git repository root
• Specify date ranges for focused changelogs
• Use CHANGELOG_STYLE.md for consistent formatting
• Review and adjust before publishing
• Save output directly to CHANGELOG.md
• Include emojis/icons for visual scanning
• Group by category for easy reading
• Link to related issues/PRs when helpful

Common Use Cases

GitHub Release Notes

## What's New in v2.5.0

[Changelog content]

**Full Changelog**: https://github.com/example/repo/compare/v2.4.0...v2.5.0

App Store Updates

What's New:
- Team workspaces for better organization
- Faster file syncing (2x speed improvement)
- Improved search with file content indexing
- Bug fixes and performance improvements

Email Updates

Subject: What's New This Week

Hi [User],

Here's what we've been working on:

✨ New Features
- Team workspaces
- Keyboard shortcuts

🔧 Improvements
- Faster sync
- Better search

🐛 Fixes
- Fixed image upload issues
- Resolved timezone problems

[Call to action]

Design Specification: {{FEATURE_NAME}}

Author: {{NAME}} Date: {{YYYY-MM-DD}} Status: {{DRAFT|REVIEW|APPROVED|IMPLEMENTED}} Reviewers: {{NAMES}}

---

Overview

Problem Statement

{{WHAT_PROBLEM_ARE_WE_SOLVING}}

Goals

• {{GOAL_1}}
• {{GOAL_2}}
• {{GOAL_3}}

Non-Goals

• {{NON_GOAL_1}}
• {{NON_GOAL_2}}

---

Background

Context

{{RELEVANT_BACKGROUND_INFO}}

Current State

{{HOW_THINGS_WORK_TODAY}}

User Research / Requirements

---

Proposed Solution

High-Level Design

{{SOLUTION_OVERVIEW}}

{{ARCHITECTURE_DIAGRAM}}

User Flow

1. User {{ACTION_1}} 2. System {{RESPONSE_1}} 3. User {{ACTION_2}} 4. System {{RESPONSE_2}}

Data Model

```{{LANGUAGE}} {{DATA_STRUCTURES}}

### API Design

#### {{ENDPOINT_NAME}}

{{METHOD}} {{PATH}}

**Request:**

{{REQUEST_BODY}}

**Response:**

{{RESPONSE_BODY}}

---

## Detailed Design

### Component 1: {{COMPONENT_NAME}}

**Purpose:** {{PURPOSE}}

**Implementation:**

{{CODE_SAMPLE}}

**Interactions:**

- Receives: {{INPUT}}
- Produces: {{OUTPUT}}
- Depends on: {{DEPENDENCIES}}

---

### Component 2: {{COMPONENT_NAME}}

**Purpose:** {{PURPOSE}}

**Implementation:**

{{DESCRIPTION}}

---

### State Management

| State | Type | Initial | Transitions |
|-------|------|---------|-------------|
| {{STATE}} | {{TYPE}} | {{VALUE}} | {{TRANSITIONS}} |

### Error Handling

| Error Case | Handling | User Message |
|------------|----------|--------------|
| {{ERROR}} | {{HANDLING}} | {{MESSAGE}} |

---

## Alternatives Considered

### Alternative 1: {{NAME}}

{{DESCRIPTION}}

**Pros:**

- {{PRO}}

**Cons:**

- {{CON}}

**Why Not:** {{REASON}}

---

### Alternative 2: {{NAME}}

{{DESCRIPTION}}

**Why Not:** {{REASON}}

---

## Security Considerations

### Threats

| Threat | Risk | Mitigation |
|--------|------|------------|
| {{THREAT}} | {{H/M/L}} | {{MITIGATION}} |

### Data Privacy

- {{PRIVACY_CONSIDERATION_1}}
- {{PRIVACY_CONSIDERATION_2}}

---

## Performance Considerations

### Expected Load

| Metric | Expected | Peak |
|--------|----------|------|
| Requests/sec | {{N}} | {{N}} |
| Response Time | {{MS}}ms | {{MS}}ms |

### Scalability

{{HOW_SOLUTION_SCALES}}

### Caching Strategy

{{CACHING_APPROACH}}

---

## Testing Strategy

### Unit Tests

- {{TEST_CASE_1}}
- {{TEST_CASE_2}}

### Integration Tests

- {{TEST_CASE_1}}
- {{TEST_CASE_2}}

### Edge Cases

- {{EDGE_CASE_1}}
- {{EDGE_CASE_2}}

---

## Rollout Plan

### Phase 1: {{PHASE_NAME}}

- {{DELIVERABLE}}
- Audience: {{WHO}}

### Phase 2: {{PHASE_NAME}}

- {{DELIVERABLE}}
- Audience: {{WHO}}

### Feature Flags

| Flag | Purpose | Default |
|------|---------|---------|
| `{{FLAG}}` | {{PURPOSE}} | {{VALUE}} |

### Rollback Criteria

- {{ROLLBACK_TRIGGER_1}}
- {{ROLLBACK_TRIGGER_2}}

---

## Monitoring & Observability

### Metrics

| Metric | Purpose | Alert Threshold |
|--------|---------|-----------------|
| {{METRIC}} | {{PURPOSE}} | {{THRESHOLD}} |

### Logging

| Event | Level | Data |
|-------|-------|------|
| {{EVENT}} | {{INFO/WARN/ERROR}} | {{DATA}} |

### Dashboards

- {{DASHBOARD_1}}
- {{DASHBOARD_2}}

---

## Dependencies

### External Dependencies

| Dependency | Purpose | Owner |
|------------|---------|-------|
| {{DEP}} | {{PURPOSE}} | {{OWNER}} |

### Internal Dependencies

- {{INTERNAL_DEP_1}}
- {{INTERNAL_DEP_2}}

---

## Open Questions

1. {{QUESTION_1}}
2. {{QUESTION_2}}

---

## Timeline

| Milestone | Date |
|-----------|------|
| Design Review | {{DATE}} |
| Implementation Start | {{DATE}} |
| Testing Complete | {{DATE}} |
| Rollout | {{DATE}} |

---

## References

- [{{DOC_1}}]({{URL}})
- [{{DOC_2}}]({{URL}})

---

## Quality Checklist

- [ ] Problem clearly stated
- [ ] Goals and non-goals defined
- [ ] Alternatives considered
- [ ] Security reviewed
- [ ] Performance considered
- [ ] Testing strategy defined
- [ ] Rollout plan documented
- [ ] Monitoring planned

Migration Guide: {{FROM_VERSION}} to {{TO_VERSION}}

Last Updated: {{DATE}} Estimated Effort: {{LOW|MEDIUM|HIGH}} Breaking Changes: {{YES|NO}}

---

Overview

{{MIGRATION_SUMMARY}}

Who Should Migrate

• [ ] All users of {{FEATURE}}
• [ ] Users with custom {{COMPONENT}}
• [ ] Self-hosted deployments

Prerequisites

• {{PREREQUISITE_1}}
• {{PREREQUISITE_2}}
• Backup your data before proceeding

---

Breaking Changes

{{BREAKING_CHANGE_1}}

Before ({{OLD_VERSION}}):

```{{LANGUAGE}} {{OLD_CODE}}

**After ({{NEW_VERSION}}):**

{{NEW_CODE}}

**Migration:**

1. {{STEP_1}}
2. {{STEP_2}}

**Automated Fix:**

{{CODEMOD_OR_SCRIPT}}

---

### {{BREAKING_CHANGE_2}}

**What Changed:** {{DESCRIPTION}}

**Impact:** {{WHO_IS_AFFECTED}}

**Action Required:**

- [ ] {{ACTION_1}}
- [ ] {{ACTION_2}}

---

## Deprecations

| Deprecated | Replacement | Removal Version |
|------------|-------------|-----------------|
| `{{OLD_API}}` | `{{NEW_API}}` | {{VERSION}} |
| `{{OLD_CONFIG}}` | `{{NEW_CONFIG}}` | {{VERSION}} |

### Deprecation Warnings

To see all deprecation warnings:

{{COMMAND_TO_SHOW_WARNINGS}}

---

## Step-by-Step Migration

### Step 1: {{STEP_TITLE}}

{{STEP_DESCRIPTION}}

{{COMMANDS}}

**Verification:**

{{VERIFICATION_COMMAND}}

Expected output:

{{EXPECTED_OUTPUT}}

---

### Step 2: {{STEP_TITLE}}

{{STEP_DESCRIPTION}}

**Before:**

{{OLD_CODE}}

**After:**

{{NEW_CODE}}

---

### Step 3: {{STEP_TITLE}}

{{STEP_DESCRIPTION}}

| Old | New |
|-----|-----|
| `{{OLD}}` | `{{NEW}}` |

---

## Configuration Changes

### Environment Variables

| Old Variable | New Variable | Default |
|--------------|--------------|---------|
| `{{OLD_VAR}}` | `{{NEW_VAR}}` | `{{DEFAULT}}` |

### Config File Changes

**Before (`{{CONFIG_FILE}}`):**

{{OLD_CONFIG}}

**After (`{{CONFIG_FILE}}`):**

{{NEW_CONFIG}}

---

## Database Migrations

### Required Migrations

{{MIGRATION_COMMAND}}

### Schema Changes

| Table | Change | SQL |
|-------|--------|-----|
| `{{TABLE}}` | {{ADD/MODIFY/DROP}} | `{{SQL}}` |

### Data Migration

{{DATA_MIGRATION_SQL}}

**Rollback:**

{{ROLLBACK_SQL}}

---

## Dependency Updates

| Package | Old Version | New Version | Notes |
|---------|-------------|-------------|-------|
| `{{PKG}}` | `{{OLD}}` | `{{NEW}}` | {{NOTES}} |

{{UPDATE_COMMAND}}

---

## API Changes

### Endpoint Changes

| Old Endpoint | New Endpoint | Method |
|--------------|--------------|--------|
| `{{OLD_PATH}}` | `{{NEW_PATH}}` | {{METHOD}} |

### Request/Response Changes

**Before:**

{{OLD_JSON}}

**After:**

{{NEW_JSON}}

---

## Troubleshooting

### Common Issues

#### {{ISSUE_1}}

**Symptom:** {{SYMPTOM}}

**Cause:** {{CAUSE}}

**Solution:**

{{SOLUTION}}

---

#### {{ISSUE_2}}

**Symptom:** {{SYMPTOM}}

**Solution:** {{SOLUTION}}

---

## Rollback Procedure

If migration fails:

1. {{ROLLBACK_STEP_1}}
2. {{ROLLBACK_STEP_2}}
3. {{ROLLBACK_STEP_3}}

{{ROLLBACK_COMMANDS}}

---

## Verification Checklist

- [ ] All tests pass
- [ ] No deprecation warnings
- [ ] Application starts successfully
- [ ] Core functionality works
- [ ] Performance acceptable
- [ ] Logs show no errors

### Smoke Tests

{{SMOKE_TEST_COMMANDS}}

---

## Support

- Documentation: {{DOCS_URL}}
- Issues: {{ISSUES_URL}}
- Community: {{COMMUNITY_URL}}

---

## Quality Checklist

- [ ] All breaking changes documented
- [ ] Code examples show before/after
- [ ] Automated migration scripts provided where possible
- [ ] Rollback procedure documented
- [ ] Verification steps included
- [ ] Troubleshooting covers common issues

Technical Writing

Best practices for technical writing, user guides, README files, architecture documentation, and content organization.

Writing Principles

Write for Your Audience

Know Your Audience:

• Skill level (beginner, intermediate, advanced)
• Technical background
• Use case and goals
• Prior knowledge assumptions

Adapt Your Writing:

• Use appropriate terminology
• Provide context when needed
• Explain acronyms and jargon
• Include troubleshooting for common issues

Lead with the Outcome

Structure:

1. What users will accomplish 2. Why it matters 3. How to do it (steps) 4. What to do next

Example:

# Setting Up Your Development Environment

By the end of this guide, you'll have a fully functional development
environment running locally. This takes about 10 minutes and requires
no prior setup experience.

## What You'll Get

- Local development server running
- Database configured and seeded
- All dependencies installed
- Ready to start coding

## Prerequisites

- Node.js 18+ installed
- Git installed
- Text editor of your choice

## Steps

[Step-by-step instructions...]

Use Active Voice

Active Voice:

• "Click the Submit button"
• "Run the test suite"
• "Install the dependencies"

Passive Voice (Avoid):

• "The Submit button should be clicked"
• "The test suite should be run"
• "Dependencies should be installed"

User Guides

Structure

1. Overview: What the guide covers and what users will learn 2. Prerequisites: What's needed before starting 3. Steps: Clear, numbered steps 4. Examples: Real examples with expected outcomes 5. Troubleshooting: Common issues and solutions 6. Next Steps: What to do after completing the guide

Example: User Guide Template

# User Guide: [Feature Name]

## What You'll Learn

By the end of this guide, you'll be able to:
- [Outcome 1]
- [Outcome 2]
- [Outcome 3]

## Prerequisites

- [Requirement 1]
- [Requirement 2]

## Step 1: [Action]

[Clear instructions with screenshots or code examples]

**Expected Result:**
[What users should see]

## Step 2: [Action]

[Continue with clear steps...]

## Troubleshooting

### Problem: [Common Issue]
**Solution**: [How to fix it]

### Problem: [Another Issue]
**Solution**: [How to fix it]

## Next Steps

- [Related guide or feature]
- [Additional resources]

README Files

Essential Sections

Required:

• Project title and description
• Installation instructions
• Quick start guide
• Usage examples
• License

Recommended:

• Badges (build status, version, license)
• Features list
• Contributing guidelines
• Changelog link
• Support/contact information

README Template

# Project Name

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://example.com)
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://example.com)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

A brief description of what your project does and why it exists.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

\`\`\`bash
npm install project-name
\`\`\`

## Quick Start

\`\`\`javascript
import { ProjectName } from 'project-name';

const instance = new ProjectName();
instance.doSomething();
\`\`\`

## Usage

[Detailed usage examples]

## Documentation

See [docs/](docs/) for full documentation.

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT

Architecture Documentation

Structure

1. Overview: High-level system architecture 2. Components: Major components and their responsibilities 3. Data Flow: How data moves through the system 4. Technology Stack: Technologies used and why 5. Design Decisions: Key architectural decisions and rationale 6. Integration Points: How components integrate 7. Scaling Considerations: How the system scales

Example: Architecture Doc Template

# System Architecture

## Overview

[High-level description of the system]

## Architecture Diagram

[Diagram showing components and relationships]

## Components

### [Component Name]
- **Purpose**: [What it does]
- **Responsibilities**: [Key responsibilities]
- **Technologies**: [Technologies used]
- **Interfaces**: [How other components interact with it]

## Data Flow

[Description of how data flows through the system]

## Technology Stack

- **Frontend**: [Framework and libraries]
- **Backend**: [Framework and libraries]
- **Database**: [Database technology]
- **Infrastructure**: [Infrastructure choices]

## Design Decisions

### Decision 1: [Decision]
**Rationale**: [Why this decision was made]
**Alternatives Considered**: [Other options]
**Trade-offs**: [What was traded off]

## Integration Points

[How components integrate with each other and external systems]

## Scaling Considerations

[How the system scales horizontally and vertically]

Code Documentation

Docstrings

Python:

def calculate_total(items):
    """
    Calculate the total price of items.

    Args:
        items: List of items with 'price' attribute

    Returns:
        float: Total price of all items

    Raises:
        ValueError: If items list is empty
    """
    if not items:
        raise ValueError("Items list cannot be empty")
    return sum(item.price for item in items)

JavaScript (JSDoc):

/**
 * Calculate the total price of items.
 *
 * @param {Array<{price: number}>} items - List of items with price
 * @returns {number} Total price of all items
 * @throws {Error} If items list is empty
 */
function calculateTotal(items) {
  if (!items.length) {
    throw new Error('Items list cannot be empty');
  }
  return items.reduce((sum, item) => sum + item.price, 0);
}

Inline Comments

When to Comment:

• Complex algorithms or business logic
• Non-obvious code decisions
• Workarounds or hacks
• Why code exists (not what it does)

When Not to Comment:

• Obvious code
• Code that restates what's already clear
• Outdated information

Content Organization

Heading Structure

Hierarchy:

• # Main Title (H1) - One per document

• ## Major Sections (H2)

• ### Subsections (H3)

• #### Details (H4)

Best Practices:

• Use descriptive headings
• Maintain consistent hierarchy
• Don't skip heading levels
• Use heading levels for structure, not styling

Navigation

Table of Contents:

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Contributing](#contributing)

Cross-References:

See [Installation Guide](./installation.md) for setup instructions.
Refer to [API Documentation](./api.md#authentication) for auth details.

Best Practices

Writing Guidelines

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

Content Quality

• Accuracy: Verify all information is correct
• Completeness: Cover all necessary topics
• Currency: Keep documentation up to date
• Consistency: Use consistent terminology and style
• Accessibility: Write for diverse audiences

Formatting

• Code Blocks: Use syntax highlighting
• Lists: Use bullet points for unordered, numbers for steps
• Tables: Use tables for structured data
• Images: Include alt text and captions
• Links: Use descriptive link text