How to Write Technical Documentation That People Actually Read

How to Write Technical Documentation That People Actually Read

I once joined a project with no documentation. To set up the development environment, I needed to: install 3 specific version-pinned tools (version numbers not specified), run 7 setup commands in a specific order (order not documented), copy a .env.example file and fill in 12 environment variables (where to get them: not documented), and run a database migration script (which one, in which order: not documented).

It took me two full days to get a working development environment. My colleague told me it had taken her three days.

"This is just how it is," she said. "The person who set this up left the company."

That project had millions of dollars of engineering investment in its code. It had zero investment in documentation. Every new developer who joined paid for that with days of lost time.

In this guide, you'll learn how to write documentation developers actually read — and how to do it efficiently enough that it becomes a habit rather than a chore.

The Four Types of Documentation

Understanding the purpose of each documentation type helps you write the right kind:

Most documentation failures happen when writers mix these types in one document. Tutorials and references have completely different readers in completely different modes.

The README: Your Most Important Document

The README is the front door to your project. It should answer five questions:

1. What is this? (One sentence)
2. What problem does it solve?
3. How do I install/set it up?
4. How do I use it? (Basic example)
5. Where is the rest of the documentation?

README Template

# ProjectName

One sentence describing what this project does.

## What It Does

2–3 sentences expanding on the one-liner. What problem does it solve?
Who is it for?

## Quick Start

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

\`\`\`javascript
import { something } from 'project-name';
// Minimal working example
\`\`\`

## Setup

\`\`\`bash
git clone https://github.com/your/project
cd project
cp .env.example .env
# Fill in your environment variables (see .env.example for descriptions)
npm install
npm run dev
\`\`\`

## Requirements

- Node.js 20+
- PostgreSQL 16+

## Documentation

Full documentation at [docs.yourproject.com](https://docs.yourproject.com)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT

The key: put the Quick Start example before anything else. Most developers skim to the first code example. If that example is compelling, they continue reading.

Writing API Documentation That Works

API documentation is the most commonly needed and most commonly bad documentation type.

Every Endpoint Needs These Six Things

## POST /api/users

Creates a new user account.

**Authentication:** Bearer token required.

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address. Must be unique. |
| name | string | Yes | Full display name (2–100 characters) |
| role | string | No | Default: 'user'. Options: 'user', 'admin' |

**Example Request:**
\`\`\`bash
curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "name": "Alice Johnson"}'
\`\`\`

**Success Response (201):**
\`\`\`json
{
  "id": "user_abc123",
  "email": "alice@example.com",
  "name": "Alice Johnson",
  "role": "user",
  "createdAt": "2025-01-15T10:30:00Z"
}
\`\`\`

**Error Responses:**
| Code | Reason |
|------|--------|
| 400 | Invalid email format or missing required fields |
| 409 | Email already in use |
| 401 | Missing or invalid authentication token |

The test for API documentation: can a developer use this endpoint correctly without reading the source code? If yes, the docs are sufficient.

Code Comments: Documentation at the Source

Code comments are the most granular form of documentation. Refer to our clean code guide for the full principle, but the key rule:

Comments explain WHY, not WHAT.

// Bad: restates what the code does
// Loop through users
for (const user of users) {

// Bad: explains obvious language feature
// Create a new object
const config = {};

// Good: explains non-obvious business rule
// Prices are stored in cents to avoid floating-point arithmetic errors
// (multiply by 100 when receiving, divide by 100 when displaying)
const priceInCents = Math.round(dollarAmount * 100);

// Good: explains a known limitation
// Note: this operation is O(n²) — acceptable for the current user count (<1000)
// but will need to be optimized before scaling to 10k+ users
const duplicates = findDuplicates(allUsers);

// Good: explains why a workaround exists
// Chrome 108 incorrectly calculates scrollTop for sticky elements.
// This forces a reflow that resolves the calculation.
element.getBoundingClientRect();

Writing Changelogs Developers Actually Read

A changelog is a human-readable list of what changed between versions. Good changelog, bad changelog:

## Bad Changelog (useless):
v2.1.0 - Various improvements and bug fixes

## Good Changelog (actionable):
## [2.1.0] - 2025-05-15

### Added
- New `POST /api/webhooks` endpoint for event subscription (see docs)
- `user.lastLoginAt` field in user responses

### Changed  
- BREAKING: `GET /api/orders` now returns items sorted by `createdAt` descending
  (previously ascending). Update any code that assumed ascending order.

### Fixed
- Fixed race condition in order processing that caused duplicate charges (affected
  orders placed within 200ms of each other)

### Security
- Updated jwt dependency to address CVE-2025-1234 (token spoofing vulnerability)

The Keep a Changelog format (keepachangelog.com) is the de facto standard. Follow it.

Breaking changes deserve special attention — mark them clearly and explain migration paths.

Automating Documentation to Keep It Current

For APIs: Swagger/OpenAPI

Write your API spec in YAML/JSON once, and generate both interactive documentation and client libraries from it:

# openapi.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string

Swagger UI generates interactive documentation from this spec — developers can try requests directly in the browser.

For JavaScript/TypeScript: JSDoc

Type annotations in TypeScript already provide a form of inline documentation:

/**
 * Calculates the final price after applying a discount code.
 * @param price - Original price in dollars (positive number)
 * @param discountCode - Optional coupon code from the DISCOUNT_CODES table
 * @returns Final price after discount, or original price if code is invalid
 * @throws {RangeError} If price is negative
 */
function applyDiscount(price: number, discountCode?: string): number {
  if (price < 0) throw new RangeError('Price cannot be negative');
  const discount = DISCOUNT_CODES[discountCode ?? ''] ?? 0;
  return price * (1 - discount);
}

Tools like TypeDoc generate full documentation sites from JSDoc comments + TypeScript types.

The Documentation-First Approach

The most effective way to ensure documentation gets written: write it first.

Before implementing a new API endpoint, write the documentation for it. Describe what it will do, what inputs it accepts, what it returns, and what errors it can produce. This forces you to think through edge cases before coding and makes the documentation accurate by definition.

This approach also catches design problems early — if the endpoint is hard to document clearly, it's probably also hard to use.

Frequently Asked Questions

Why do developers hate writing documentation?

Most were never taught how. Documentation feels unrewarded. The mindset shift: documentation is for your future self and your team. 15 minutes today saves 2 hours next month.

What documentation should I write first?

The README. Every project needs a README answering: what is this, how do I set it up, how do I run it, and how do I deploy. A good README cuts onboarding from hours to minutes.

What belongs in API documentation?

Method and path, what it does, authentication requirements, parameters with types, example request, all response codes with examples, and error formats.

How long should documentation be?

As long as necessary to be clear, as short as possible to be scannable. Use headers and bullet points. Put the most important information first. Include code examples for everything.

How do I keep documentation up to date?

Make documentation updates part of the definition of done — PRs cannot merge without doc updates. For APIs, use OpenAPI/Swagger to auto-generate docs from code annotations.