Documentation

Documentation

Overview

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

---

Documentation Types

---

README Best Practices

Structure

# 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

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

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

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: "user@example.com"
                    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: User's email address
        name:
          type: string
          description: User's display name

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid or missing API key"

Code Examples in Docs

## Creating a User

### Request

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" }'

### Response

{ "id": "usr_123", "email": "user@example.com", "name": "John Doe", "createdAt": "2024-01-15T10:30:00Z" }

### Error Response

{ "error": { "code": "validation_error", "message": "Invalid email format", "field": "email" } }

---

Architecture Decision Records (ADR)

Template

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
We need to choose a primary database for our application.
Requirements:
- ACID transactions
- Complex queries with joins
- Proven reliability at scale
- Good ecosystem and tooling

## Decision
We will use PostgreSQL as our primary database.

## Alternatives Considered

### MySQL
- Pros: Widely used, good performance
- Cons: Less feature-rich, weaker JSON support

### MongoDB
- Pros: Flexible schema, easy horizontal scaling
- Cons: No ACID transactions across documents, eventual consistency

### CockroachDB
- Pros: Distributed, PostgreSQL-compatible
- Cons: Higher operational complexity, newer technology

## Consequences

### Positive
- Strong consistency guarantees
- Rich query capabilities (CTEs, window functions)
- Excellent JSON support for semi-structured data
- Large community and ecosystem

### Negative
- Vertical scaling limits
- Need to manage read replicas for high read loads
- Schema migrations require careful planning

### Risks
- May need sharding solution if we exceed single-node capacity
- Team needs PostgreSQL expertise

## References
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Internal benchmark results](link)

ADR Index

# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-001](adr-001.md) | Use PostgreSQL | Accepted | 2024-01-01 |
| [ADR-002](adr-002.md) | JWT Authentication | Accepted | 2024-01-05 |
| [ADR-003](adr-003.md) | Microservices Split | Proposed | 2024-01-10 |
| [ADR-004](adr-004.md) | GraphQL vs REST | Superseded by ADR-006 | 2024-01-15 |

---

Code Documentation

JSDoc / TSDoc

/**
 * Calculates the total price including tax and discounts.
 *
 * @param items - Array of cart items
 * @param options - Calculation options
 * @returns The calculated price breakdown
 *
 * @example
 * ```typescript
 * const result = calculatePrice(
 *   [{ id: '1', price: 100, quantity: 2 }],
 *   { taxRate: 0.1, discountCode: 'SAVE10' }
 * );
 * console.log(result.total); // 198
 * ```
 *
 * @throws {ValidationError} If items array is empty
 * @throws {InvalidDiscountError} If discount code is invalid
 *
 * @see {@link applyDiscount} for discount logic
 * @since 2.0.0
 */
function calculatePrice(
  items: CartItem[],
  options: PriceOptions
): PriceBreakdown {
  // Implementation
}

/**
 * Represents a user in the system.
 *
 * @remarks
 * Users are created through the signup flow or admin panel.
 * Soft deletion is used - check `deletedAt` for active status.
 */
interface User {
  /** Unique identifier (UUID v4) */
  id: string;

  /** Email address (unique, validated format) */
  email: string;

  /**
   * User's display name
   * @defaultValue Derived from email if not provided
   */
  name?: string;

  /** Account creation timestamp */
  createdAt: Date;

  /** Soft deletion timestamp, null if active */
  deletedAt: Date | null;
}

Inline Comments

// ✅ Good: Explains WHY
// Use binary search because items are sorted and list can have 100k+ entries
const index = binarySearch(items, target);

// ✅ Good: Explains non-obvious behavior
// Sleep 100ms to avoid rate limiting from external API
await sleep(100);

// ✅ Good: Documents workaround
// HACK: Safari doesn't support this API, fall back to polyfill
// TODO: Remove when Safari 17 adoption > 90%
const result = window.api?.call() ?? polyfill();

// ❌ Bad: States the obvious
// Loop through users
for (const user of users) {

// ❌ Bad: Outdated comment
// Returns user's full name (actually returns email now)
function getUserIdentifier() {
  return user.email;
}

---

Runbooks

Structure

# Runbook: High Memory Usage Alert

## Overview
This runbook addresses alerts when application memory usage exceeds 80%.

## Prerequisites
- Access to Kubernetes cluster
- Permissions to view pods and logs
- Familiarity with application architecture

## Symptoms
- Alert: `HighMemoryUsage` firing
- Metric: `container_memory_usage_bytes` > 80% of limit
- Possible: OOMKilled pods, slow responses

## Diagnosis

### Step 1: Identify affected pods

kubectl top pods -n production | sort -k3 -rh | head -10

### Step 2: Check for memory leaks

Get heap dump

kubectl exec -it <pod> -- node --heapsnapshot kubectl cp <pod>:/app/heapsnapshot.heapsnapshot ./heapsnapshot.heapsnapshot

### Step 3: Check recent deployments

kubectl rollout history deployment/api -n production

## Mitigation

### Immediate (if pods are crashing)

Scale up to distribute load

kubectl scale deployment/api --replicas=10

Restart pods (rolling)

kubectl rollout restart deployment/api

### If memory leak confirmed
1. Identify the leaking code path from heap snapshot
2. Prepare hotfix
3. Deploy fix following standard process

## Resolution
- Memory usage returns below 70%
- No OOMKilled events for 30 minutes
- Alert auto-resolves

## Escalation
- L1: On-call engineer
- L2: Platform team (if infrastructure issue)
- L3: Application team lead (if code issue)

## Related
- [Memory Profiling Guide](link)
- [Incident INC-123](link) - Previous memory leak

---

Documentation Tools

---

Related Skills

• [[api-design]] - API documentation
• [[code-quality]] - Self-documenting code
• [[reliability-engineering]] - Runbooks

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 that was added

Changed

• Changes in existing functionality

Deprecated

• Soon-to-be removed features

Removed

• Features that were removed

Fixed

• Bug fixes

Security

• Security improvements

[1.0.0] - 2024-01-15

Added

• Initial release
• Core functionality
• Documentation
• Test suite

[0.2.0] - 2024-01-10

Added

• New API endpoint for data retrieval
• Support for environment variable configuration
• Retry logic with exponential backoff

Changed

• Updated dependency X to version 2.0
• Improved error messages

Fixed

• Fixed memory leak in connection pool
• Fixed race condition in async operations

[0.1.1] - 2024-01-05

Fixed

• Fixed critical bug in authentication flow
• Fixed incorrect error handling

Security

• Updated vulnerable dependency Y

[0.1.0] - 2024-01-01

Added

• Initial beta release
• Basic authentication
• Core API methods

---

<!-- Link definitions --> [Unreleased]: https://github.com/org/project/compare/v1.0.0...HEAD [1.0.0]: https://github.com/org/project/compare/v0.2.0...v1.0.0 [0.2.0]: https://github.com/org/project/compare/v0.1.1...v0.2.0 [0.1.1]: https://github.com/org/project/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/org/project/releases/tag/v0.1.0

<!--

Changelog Guidelines

Version Types (Semantic Versioning)

• MAJOR (1.0.0): Breaking changes
• MINOR (0.1.0): New features, backwards compatible
• PATCH (0.0.1): Bug fixes, backwards compatible

Change Types

• Added: New features
• Changed: Changes to existing features
• Deprecated: Features to be removed
• Removed: Removed features
• Fixed: Bug fixes
• Security: Security-related changes

Format

• Use present tense ("Add feature" not "Added feature")
• Start with a verb (Add, Fix, Update, Remove, etc.)
• Reference issues/PRs when relevant (#123)
• Keep entries concise but informative

Examples

• Add user authentication with JWT
• Fix memory leak in WebSocket handler (#123)
• Update Node.js requirement to v18+
• Remove deprecated legacyMethod() function
• Security: Update axios to patch CVE-2024-XXXX

-->

Project Name

  <!-- Add relevant badges: build status, coverage, npm version, etc. -->

Short description of what this project does and why it's useful.

Features

• ✨ Feature one with brief description
• 🚀 Feature two with brief description
• 🔒 Feature three with brief description

Quick Start

# Install
npm install project-name

# Or using yarn
yarn add project-name

// Basic usage
import { something } from 'project-name';

const result = something.do();

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Install

npm install project-name

From Source

git clone https://github.com/org/project-name.git
cd project-name
npm install
npm run build

Usage

Basic Example

import { Client } from 'project-name';

const client = new Client({
  apiKey: process.env.API_KEY,
});

const result = await client.doSomething({
  param1: 'value1',
  param2: 'value2',
});

console.log(result);

Configuration

Environment Variables

# .env
PROJECT_API_KEY=your-api-key
PROJECT_TIMEOUT=30000

API Reference

Client

Constructor

new Client(options: ClientOptions)

Methods

doSomething(params)

Does something useful.

Parameters:

• params.param1 (string): Description
• params.param2 (string, optional): Description

Returns: Promise<Result>

Example:

const result = await client.doSomething({ param1: 'value' });

Development

Setup

git clone https://github.com/org/project-name.git
cd project-name
npm install
cp .env.example .env

Commands

npm run dev      # Start development server
npm run build    # Build for production
npm run test     # Run tests
npm run lint     # Run linter

Project Structure

project-name/
├── src/
│   ├── index.ts        # Main entry point
│   ├── client.ts       # Client implementation
│   └── utils/          # Utility functions
├── tests/              # Test files
├── docs/               # Documentation
└── examples/           # Example code

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- --grep "Client"

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository 2. Create your feature branch (git checkout -b feature/amazing-feature) 3. Commit your changes (git commit -m 'Add amazing feature') 4. Push to the branch (git push origin feature/amazing-feature) 5. Open a Pull Request

Troubleshooting

Common Issues

Error: API key not found

Make sure you've set the PROJECT_API_KEY environment variable.

Error: Connection timeout

Increase the timeout option or check your network connection.

FAQ

<details> <summary>How do I do X?</summary>

Answer to the question about doing X. </details>

<details> <summary>Why does Y happen?</summary>

Explanation of why Y happens and how to handle it. </details>

Roadmap

• [ ] Feature A
• [ ] Feature B
• [x] Feature C (completed)

See CHANGELOG.md for recent changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Dependency A - What it's used for
• Inspiration - Source of inspiration

Support

• 📖 Documentation
• 💬 Discord
• 🐛 Issues

Documentation Templates

Templates for project documentation.

Files

Usage

README

# Copy template
cp templates/README-template.md ./README.md

# Edit and customize
# Replace placeholders with actual project info

CHANGELOG

# Copy template
cp templates/CHANGELOG-template.md ./CHANGELOG.md

# Add entries as you release versions

README Sections

Essential

Recommended

Optional

CHANGELOG Format

Based on Keep a Changelog:

## [1.0.0] - 2024-01-15

### Added
- New feature X

### Changed
- Updated Y behavior

### Fixed
- Bug in Z (#123)

Change Types

Semantic Versioning

MAJOR.MINOR.PATCH

1.0.0 → 2.0.0  # Breaking changes
1.0.0 → 1.1.0  # New features
1.0.0 → 1.0.1  # Bug fixes

Best Practices

README

• Start with clear value proposition
• Include working code examples
• Keep Quick Start under 5 commands
• Use badges for status at a glance
• Link to detailed docs

CHANGELOG

• Update with each release
• Use present tense ("Add" not "Added")
• Reference issue/PR numbers
• Keep unreleased section updated
• Link versions to GitHub comparisons

Additional Templates

Consider also creating:

docs/
├── README.md           # Main docs index
├── CONTRIBUTING.md     # Contribution guide
├── CODE_OF_CONDUCT.md  # Community standards
├── SECURITY.md         # Security policy
├── ADR/                # Architecture decisions
│   └── 001-choice.md
└── api/                # API documentation
    └── endpoints.md