Documenting

Documentation Types

| Type | Audience | Content | | --------- | ------------ | --------------------------------- | | README | New users | Quick start, installation, usage | | API docs | Developers | Endpoints, parameters, responses | | Code docs | Contributors | Architecture, patterns, decisions | | Comments | Code readers | Why, not what |

README Structure

# Project Name

Brief description (1-2 sentences).

## Quick Start

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

## Usage

\`\`\`typescript
import { feature } from 'project-name';
// Minimal working example
\`\`\`

## API Reference

Link to detailed docs or brief overview.

## Contributing

How to contribute, run tests, submit PRs.

## License

License type and link.

Code Comments

// Good - explains WHY
// Cache invalidated after 5 minutes to balance freshness vs API rate limits
const CACHE_TTL = 300_000;

// Bad - explains WHAT (obvious from code)
// Set cache TTL to 300000
const CACHE_TTL = 300_000;

JSDoc Format

/**
 * Calculates the total price including tax.
 *
 * @param items - Cart items to calculate
 * @param region - Tax region (affects rate)
 * @returns Total price in cents
 * @throws {ValidationError} If items array is empty
 *
 * @example
 * const total = calculateTotal([{ price: 1000 }], 'EU');
 * // Returns: 1210 (with 21% VAT)
 */
function calculateTotal(items: Item[], region: Region): number {

Principles

1. Audience-first: Write for the reader, not yourself
2. Examples over explanation: Show, don't just tell
3. Keep current: Outdated docs are worse than none
4. DRY: Link to existing docs, don't duplicate
5. Scannable: Use headings, lists, tables