Overview

Create clear, useful documentation that helps people understand and use your code.

Core Principle

Write for the reader, not for yourself.

Types of Documentation

1. README Files

Purpose: Help users understand what the project does and how to use it

Audience: New users, potential contributors

Key sections:

• What it does (one paragraph)
• Installation instructions
• Quick start example
• Common use cases
• Link to full documentation
• How to contribute
• License

2. API Documentation

Purpose: Help developers use your API correctly

Audience: Other developers integrating with your code

Key information:

• Endpoint/function signature
• Parameters and types
• Return values
• Error cases
• Authentication requirements
• Examples

3. Inline Comments

Purpose: Explain non-obvious decisions and complex logic

Audience: Future developers (including future you)

When to add:

• Non-obvious decisions ("why" not "what")
• Complex algorithms
• Workarounds
• Edge cases
• Performance considerations
• Security considerations

4. Technical Guides

Purpose: Teach how to accomplish specific tasks

Audience: Developers working with the system

Types:

• How-to guides (step-by-step)
• Architecture overviews (system structure)
• Integration guides (connecting systems)
• Troubleshooting guides (debugging help)

5. Architecture Decision Records (ADRs)

Purpose: Document important technical decisions and their rationale

Audience: Current and future team members

Key information:

• Context (what problem exists)
• Decision (what was chosen)
• Alternatives considered
• Consequences (trade-offs)

README Template

# Project Name

Brief description (one paragraph) of what this project does and why it exists.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install project-name

Quick Start

import { Thing } from 'project-name'

const thing = new Thing()
thing.doSomething()
// Output: ...

Usage

Basic Usage

[Most common use case with complete example]

Advanced Usage

[More complex scenarios]

API Reference

functionName(param1, param2)

Description of what the function does.

Parameters:

• param1 (string, required): Description of parameter
• param2 (number, optional): Description with default. Default: 42

Returns: string - Description of return value

Throws:

• Error - When parameter is invalid

Example:

const result = functionName('hello', 10)
console.log(result) // "hello repeated 10 times"

Configuration

[How to configure, if applicable]

Troubleshooting

Error: "Cannot find module"

Cause: Package not installed Solution:

npm install project-name

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE file for details.

## API Documentation Template

### REST API

```markdown
## POST /api/users

Create a new user account.

### Authentication

Requires admin access token in Authorization header.

### Request

**Headers:**
```json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer <admin_token>"
}

Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

Body Parameters:

• email (string, required): Valid email address. Must be unique.
• name (string, required): User's full name. 2-100 characters.
• role (string, optional): User role. One of: "user", "admin". Default: "user".

Response

Success (201 Created):

{
  "id": "abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses:

400 Bad Request:

{
  "error": "Invalid email format",
  "field": "email"
}

401 Unauthorized:

{
  "error": "Authentication required"
}

403 Forbidden:

{
  "error": "Admin access required"
}

409 Conflict:

{
  "error": "Email already exists",
  "field": "email"
}

429 Too Many Requests:

{
  "error": "Rate limit exceeded. Try again in 60 seconds.",
  "retryAfter": 60
}

Example

cURL:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abc123..." \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }'

JavaScript:

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer abc123...'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    name: 'John Doe',
    role: 'user'
  })
})

const user = await response.json()
console.log(user.id) // "abc123"

Rate Limiting

• 100 requests per minute per API key
• Returns 429 when exceeded
• Check X-RateLimit-Remaining header

### Function/Method Documentation

```typescript
/**
 * Calculate the total price including tax and shipping.
 *
 * Tax is calculated on the subtotal, not including shipping.
 * Free shipping is applied for orders over $50.
 *
 * @param items - Array of cart items with price and quantity
 * @param shippingAddress - Shipping address for tax calculation
 * @returns Object containing subtotal, tax, shipping, and total
 *
 * @throws {Error} If items array is empty
 * @throws {Error} If any item has invalid price or quantity
 *
 * @example
 * ```typescript
 * const total = calculateTotal([
 *   { price: 10, quantity: 2 },
 *   { price: 15, quantity: 1 }
 * ], { state: 'CA' })
 *
 * console.log(total)
 * // {
 * //   subtotal: 35,
 * //   tax: 2.80,
 * //   shipping: 0,
 * //   total: 37.80
 * // }
 * ```
 */
function calculateTotal(
  items: CartItem[],
  shippingAddress: Address
): OrderTotal {
  // Implementation...
}

Inline Comment Guidelines

When to Comment

✅ DO comment:

• Why: Explains reasoning for non-obvious decisions
• Trade-offs: Documents deliberate choices
• Workarounds: Explains temporary solutions
• Complex logic: Clarifies difficult algorithms
• Edge cases: Documents special handling
• Performance: Explains optimization choices
• Security: Notes security considerations

❌ DON'T comment:

• What: Code is self-explanatory
• Redundant: Comment repeats code
• Obvious: Anyone can see what it does

Good vs Bad Comments

// ❌ BAD: States the obvious
// Loop through users
for (const user of users) {
  // Print user name
  console.log(user.name)
}

// ✅ GOOD: Explains why
// Process in creation order to maintain referential integrity
// (newer records may reference older ones)
for (const user of users.sort((a, b) => a.createdAt - b.createdAt)) {
  processUser(user)
}

// ❌ BAD: Redundant
// Add 1 to counter
counter = counter + 1

// ✅ GOOD: Explains non-obvious decision
// +1 offset because API uses 1-based indexing (not 0-based)
const pageNumber = index + 1

// ❌ BAD: Explains what (obvious)
function calculateTotal(price, quantity) {
  // Multiply price by quantity
  return price * quantity
}

// ✅ GOOD: Explains why (non-obvious)
function calculateTotal(price, quantity) {
  // Use Number.toFixed(2) to prevent floating point errors
  // (0.1 + 0.2 !== 0.3 in JavaScript)
  return Number((price * quantity).toFixed(2))
}

// ❌ BAD: Commented-out code
function processOrder(order) {
  // const tax = order.subtotal * 0.08
  const tax = calculateTax(order)
  return order.subtotal + tax
}

// ✅ GOOD: Explains temporary workaround
function processOrder(order) {
  // TODO: Remove when new tax API is deployed (JIRA-123)
  // Using hardcoded rate temporarily during migration
  const tax = order.subtotal * 0.08
  return order.subtotal + tax
}

Comment Formats

Single-line comments:

// For brief explanations
const tax = subtotal * TAX_RATE  // Updated quarterly

Multi-line comments:

/*
 * For longer explanations that span multiple lines.
 * Use when context requires more detail.
 */

Doc comments (JSDoc/TSDoc):

/**
 * For API documentation.
 * Parsed by documentation generators.
 * @param name - Parameter description
 * @returns Return value description
 */

TODO comments:

// TODO(username): Description of what needs to be done
// FIXME: Description of what's broken and needs fixing
// HACK: Description of temporary workaround
// NOTE: Important information to highlight

Technical Guide Template

# How to [Task Name]

Brief description of what this guide teaches and who should use it.

## Prerequisites

- Requirement 1
- Requirement 2
- Knowledge/tools needed

## Overview

High-level explanation of the process or concept.

## Step-by-Step Instructions

### Step 1: [First Action]

Detailed description of what to do.

```bash
# Command to run
command --option value

Expected result: What you should see.

If something goes wrong: How to troubleshoot.

Step 2: [Next Action]

[Continue with clear steps...]

Example

Complete working example showing the entire process.

// Full code example

Common Issues

Issue: [Problem Description]

Symptom: What you see when this happens. Cause: Why it happens. Solution: How to fix it.

Related Documentation

• [Link to related guide]
• [Link to API docs]

Next Steps

• [What to do after completing this guide]

## Architecture Decision Record Template

```markdown
# ADR-###: [Decision Title]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** YYYY-MM-DD
**Deciders:** [Names of decision makers]

## Context

What is the issue we're trying to solve? What factors are at play?
What constraints exist?

## Decision

What did we decide to do?

## Alternatives Considered

### Alternative 1: [Name]

**Description:** Brief explanation

**Pros:**
- Advantage 1
- Advantage 2

**Cons:**
- Disadvantage 1
- Disadvantage 2

**Why not chosen:** Explanation

### Alternative 2: [Name]

[Same structure...]

## Consequences

### Positive

- Benefit 1
- Benefit 2

### Negative

- Drawback 1
- Drawback 2

### Neutral

- Trade-off 1
- Trade-off 2

## Implementation Notes

Any specific guidance for implementing this decision.

## References

- [Related documentation]
- [Discussion links]
- [Research sources]

Documentation Best Practices

1. Write for Your Audience

Different audiences need different docs:

• New users: Quick start, common use cases
• API consumers: Complete reference, examples
• Contributors: Architecture, dev setup
• Maintainers: Design decisions, trade-offs

2. Show, Don't Just Tell

Bad:

The function accepts parameters and returns a result.

Good:

function calculateTotal(items, tax) {
  return items.reduce((sum, item) => sum + item.price, 0) * (1 + tax)
}

// Example usage:
const items = [{ price: 10 }, { price: 20 }]
const total = calculateTotal(items, 0.08) // 32.40

3. Keep Examples Runnable

Test your examples:

• Copy/paste should work
• Include all imports
• Show complete code, not fragments
• Verify examples actually run

4. Maintain Documentation

Documentation rots:

• Update docs when code changes
• Include doc updates in PRs
• Review docs periodically
• Mark outdated docs clearly

5. Use Clear Language

Avoid jargon:

• Bad: "Leverages polymorphic memoization"
• Good: "Caches results based on input type"

Be specific:

• Bad: "It's fast"
• Good: "Responds in < 100ms for 95% of requests"

Use active voice:

• Bad: "The request is processed by the server"
• Good: "The server processes the request"

Documentation Checklist

README

• Clear description of what project does
• Installation instructions
• Quick start example
• Link to full documentation
• How to contribute
• License information

API Docs

• All public APIs documented
• Parameters described with types
• Return values described
• Error cases documented
• Examples provided
• Authentication requirements stated

Inline Comments

• Complex logic explained
• Non-obvious decisions documented
• Workarounds noted
• No redundant comments
• No commented-out code
• TODOs have owner and context

Technical Guides

• Prerequisites listed
• Steps are clear and ordered
• Examples are complete and runnable
• Common issues addressed
• Related docs linked

Integration with Other Skills

• Use explainer skill for creating clear explanations
• Use proof-of-work skill to verify examples actually work
• Reference architecture-design skill for architecture documentation
• Reference technical-planning skill for implementation guides

Common Documentation Mistakes

❌ No Examples

Bad: "Use the function to process data" Good: "Use processData(items) to validate and format user input"

❌ Outdated Information

Bad: Docs say version 1.0, code is version 3.0 Good: Update docs with code changes

❌ Assuming Knowledge

Bad: "Simply configure the flux capacitor" Good: "Add FLUX_CAPACITOR=true to your .env file"

❌ Incomplete Examples

Bad:

const result = doSomething()

Good:

import { doSomething } from 'my-package'

const result = doSomething({
  option1: 'value',
  option2: 42
})
console.log(result) // Expected output

❌ Too Much Documentation

Bad: Document every single line Good: Document the "why" and non-obvious parts

Remember

1. Write for the reader - What do they need to know?
2. Show with examples - Working code is clearer than prose
3. Keep it updated - Stale docs are worse than no docs
4. Test examples - Verify they actually work
5. Explain "why" - The "what" is in the code

Good documentation helps people use your code correctly and efficiently.