Documentation Generation

Overview

Good documentation is the gift you give your future self and your team. It is NOT optional.

Core principle: Documentation describes behavior, not code. If the code changes, update the docs.

Iron Law:

DOCS ARE OUTDATED THE MOMENT THEY ARE WRITTEN — AUTOMATE OR ACCEPT THE DEBT

When to Use

• Creating a new project README
• Documenting new API endpoints
• Generating CHANGELOG entries
• Writing architecture decision records (ADRs)
• Creating onboarding guides for new team members
• Documenting AI rules for multi-tool projects

Document Types & Templates

1. README.md

A good README answers: What is this? How do I run it? How do I use it?

# Project Name

One-sentence description of what this does and who it's for.

## Quick Start

\`\`\`bash
npm install
npm run dev
\`\`\`

## Features

- Feature 1: Brief description
- Feature 2: Brief description

## Installation

\`\`\`bash
# Prerequisites
node >= 18
npm >= 9

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your values

# Run
npm start
\`\`\`

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `3000` | Server port |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |

## API Reference

See [API Documentation](./docs/api.md) for full reference.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT

2. API Documentation

# API Reference

## Authentication

All endpoints require Bearer token:
\`\`\`
Authorization: Bearer <token>
\`\`\`

## Endpoints

### GET /users

List all users.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | No | Page number (default: 1) |
| `limit` | integer | No | Per-page count (default: 20, max: 100) |

**Response:**
\`\`\`json
{
  "data": [{ "id": "123", "email": "[email protected]" }],
  "meta": { "total": 42, "page": 1 }
}
\`\`\`

**Errors:**
| Code | Status | Description |
|------|--------|-------------|
| `UNAUTHORIZED` | 401 | Missing or invalid token |
| `FORBIDDEN` | 403 | Insufficient permissions |

3. Architecture Decision Record (ADR)

# ADR-001: Use NestJS for MCP Server

**Date:** 2024-01-15
**Status:** Accepted

## Context

We need a Node.js framework for the MCP server with dependency injection and testability.

## Decision

Use NestJS with TypeScript.

## Rationale

- Built-in dependency injection for testable code
- Decorator-based approach matches MCP patterns
- Strong TypeScript support
- Module system aligns with MCP's separation of concerns

## Consequences

- Higher initial complexity than Express
- Requires understanding of NestJS modules
- Excellent testing support out of the box

4. CHANGELOG

Follow Keep a Changelog format:

# Changelog

## [Unreleased]

### Added
- New feature X

## [1.2.0] - 2024-01-15

### Added
- Support for SSE transport mode
- Bearer token authentication for SSE

### Changed
- Improved error messages for invalid rules

### Fixed
- Memory leak in rule file watcher

### Security
- Fixed token exposure in debug logs

## [1.1.0] - 2024-01-01
...

Generation Process

Step 1: Gather Context

# Understand the project structure
ls -la
cat package.json
git log --oneline -20   # Recent changes for CHANGELOG

# Find existing documentation
find . -name "*.md" -not -path "*/node_modules/*"

Step 2: Extract Information from Code

For TypeScript projects, extract JSDoc/TSDoc:

/**
 * Search rules by query string.
 * @param query - Search term to match against rule content
 * @param options - Optional filters
 * @returns Matching rules sorted by relevance
 */
async searchRules(query: string, options?: SearchOptions): Promise<Rule[]>

For configuration:

// Extract environment variables
grep -rn "process.env\." src/ | grep -o "process\.env\.[A-Z_]*" | sort -u

Step 3: Write Documentation

Principles:

• Show, don't just tell — Include working examples for every major feature
• Start with Why — First sentence explains purpose, not mechanism
• One job per section — Each section answers one question
• Concrete over abstract — Specific examples beat generic descriptions

Step 4: Verify Accuracy

- [ ] All code examples are runnable
- [ ] Environment variables list matches .env.example
- [ ] API endpoints match actual routes
- [ ] Prerequisites match actual requirements
- [ ] Links are not broken

Documentation Checklist by Type

README

• [ ] One-line description at top
• [ ] Quick Start (< 5 steps to run)
• [ ] Configuration table (all env vars)
• [ ] At least one working code example
• [ ] Link to full docs / contributing guide

API Docs

• [ ] Authentication documented
• [ ] All endpoints listed
• [ ] Request/response examples for each
• [ ] Error codes documented
• [ ] Rate limits documented

CHANGELOG

• [ ] Follows semver (MAJOR.MINOR.PATCH)
• [ ] Added / Changed / Deprecated / Removed / Fixed / Security sections
• [ ] Each entry links to issue/PR
• [ ] Unreleased section at top

ADR

• [ ] Context explains why decision was needed
• [ ] Alternatives considered
• [ ] Decision and rationale clear
• [ ] Consequences (positive and negative) listed

Common Mistakes

Tools to Accelerate

# TypeScript → API docs
npx typedoc --out docs/api src/

# Markdown linting
npx markdownlint-cli "**/*.md"

# Link checking
npx markdown-link-check README.md

# CHANGELOG generation from git log
npx conventional-changelog-cli -p angular