Pragmatic Documentation

Write documentation that respects the reader's time, explains why before how, uses real examples instead of abstract descriptions, and isn't afraid to have an opinion. Inspired by Philip Greenspun's approach: start with the big idea, show real code in context, acknowledge trade-offs honestly, and stop writing before the reader stops reading.

Core Principles

1. Start With Why

Every document opens with The Big Idea: what this thing is, why it exists, and what problem it solves — in 1–3 paragraphs. If you can't explain why someone should care in three paragraphs, you don't understand the project well enough.

Bad: "This module provides a flexible, extensible, enterprise-grade solution for..." Good: "Users kept asking the same five questions. This tool answers them automatically so maintainers can sleep."

2. Examples Over Abstractions

A single real example communicates more than three paragraphs of explanation. Show actual commands, real data, genuine output. Never invent foo, bar, WidgetFactory, or MyApp when you can show a concrete scenario.

Weave code into the narrative — don't banish it to a separate "Examples" ghetto. When explaining a data model, show the schema right there. When explaining a CLI, show the command and its output inline.