documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: documentation
description: Technical writing, API docs, and documentation best practices
domain: software-engineering
version: 1.0.0
tags: [documentation, technical-writing, api-docs, adr, readme, runbooks]
triggers:
  keywords:
    primary: [documentation, docs, readme, api docs, technical writing, wiki]
    secondary: [adr, runbook, changelog, jsdoc, docstring, swagger, typedoc]
  context_boost: [write, explain, onboarding, knowledge]
  context_penalty: [deployment, infrastructure, testing]
  priority: medium
---

# Documentation

## Overview

Documentation as a first-class engineering artifact. Good docs reduce onboarding time, support tickets, and cognitive load.

---

## Documentation Types

| Type | Audience | Purpose | Update Frequency |
|------|----------|---------|------------------|
| README | New developers | Quick start | Per major change |
| API Docs | API consumers | Reference | Per API change |
| Architecture | Team | Design decisions | Per design change |
| Runbooks | Operations | Incident response | Per incident |
| Tutorials | Users | Learning | Periodically |

---

## README Best Practices

### Structure

```markdown
# Project Name

> One-line description of what this project does.

[![Build Status](badge)](link)
[![Coverage](badge)](link)
[![License](badge)](link)

## Features

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

## Quick Start

```bash
# Install
npm install my-project

# Configure
export API_KEY=your-key

# Run
npx my-project start
```

## Installation

### Prerequisites
- Node.js 18+
- PostgreSQL 15+

### Steps
1. Clone the repository
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env`
4. Run migrations: `npm run db:migrate`
5. Start the server: `npm start`

## Usage

### Basic Example
```javascript
import { Client } from 'my-project';

const client = new Client({ apiKey: 'xxx' });
const result = await client.doSomething();
```

### Advanced Configuration
[Link to detailed docs]

## API Reference

[Link to API docs]

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT - see [LICENSE](LICENSE)
```

---

## API Documentation

### OpenAPI/Swagger

```yaml
openapi: 3.0.3
info:
  title: User API
  description: |
    API for managing users.

    ## Authentication
    All endpoints require Bearer token authentication.

    ## Rate Limiting
    - 100 requests per minute per API key
    - 429 response when exceeded
  version: 1.0.0

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

paths:
  /users:
    get:
      summary: List users
      description: Returns a paginated list of users.
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          description: Maximum number of users to return
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
              example:
                data:
                  - id: "usr_123"
                    email: "[email protected]"
                    name: "John Doe"
                meta:
                  hasMore: true
                  nextCursor: "eyJpZCI6MTIzfQ"
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: Unique identifier
          example: "usr_123"
        email:
          type: string
          format: email
          description: