documentation-generation

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 |