README-Driven Development: Write the Docs First

README-Driven Development is a simple idea: write the README before you write any code. It forces you to think about the user experience before getting lost in implementation details.

The problem it solves

Most projects start with code and add documentation as an afterthought. This leads to:

• APIs that are hard to use because the interface was designed around implementation constraints
• Missing documentation because by the time the code works, nobody wants to write docs
• Scope creep because without a clear spec, features expand during implementation
• Wasted effort building things users don't actually need

How it works

Step 1: Write the README

Before creating any files, write a README that describes:

1. What the project does — One paragraph, plain language
2. Installation — The exact commands someone will run
3. Usage — Code examples showing the primary API
4. Configuration — Every option, with defaults
5. Contributing — How to set up the dev environment

# quick-cache

A fast, type-safe caching library for Node.js with TTL support.

## Installation

\`\`\`bash
npm install quick-cache
\`\`\`

## Usage

\`\`\`typescript
import { Cache } from "quick-cache";

const cache = new Cache({ ttl: 60_000 }); // 60 second TTL

cache.set("user:123", { name: "Jane" });
const user = cache.get("user:123"); // typed as { name: string } | undefined
\`\`\`

Step 2: Review the README

Share the README with someone. Can they understand:

• What the project does without reading the code?
• How to install and start using it?
• What the API looks like?

If not, iterate on the README. This is much cheaper than iterating on code.

Step 3: Build to match the README

Now write code that makes the README examples work. The README is your specification. If you find yourself wanting to deviate from it, update the README first, then update the code.

Why it works

Forces good API design

When you write usage examples first, you naturally design APIs from the consumer's perspective. You'll catch awkward interfaces before they exist:

// This feels wrong when you write the example:
const result = cache.get("key", { deserialize: true, checkTtl: true });

// This feels right:
const result = cache.get("key");

Prevents over-engineering

A README scoped to real use cases keeps you focused. You won't build a plugin system when the README only shows three methods.

Documentation stays accurate

Since the docs come first, they match the implementation by definition. The README is always up to date because it was the blueprint.

Clarifies scope for teams

For team projects, the README becomes the proposal. Before writing code, the team reviews the README. Disagreements about interface design surface in a document review, not in a code review.

When to use it

RDD works best for:

• Libraries and SDKs — Where the public API is the product
• CLI tools — Where the command interface defines the UX
• APIs — Where endpoint design matters
• New features — Where scope needs to be defined upfront

It's less useful for:

• Exploratory prototypes — Where you're still discovering what to build
• Internal scripts — Where there's no external user
• Bug fixes — Where the README won't change

Practical tips

1. Start with examples, not prose. Write the code snippets first, then add explanatory text around them.
2. Include error cases. Show what happens when things go wrong — this forces you to design error handling early.
3. Write installation instructions you'd follow. If the setup requires more than 3 commands, simplify the tool.
4. Version your README. Track README changes alongside code changes. If the interface changes, the README changes first.
5. Use real variable names. Don't use foo and bar in examples — use names that reflect actual use cases.

Getting started with RDD

The easiest way to try RDD is on your next small project. Write the README, share it for feedback, then build. You'll be surprised how much clearer the implementation becomes.

If you have existing projects that need better READMEs, generate one from your codebase as a starting point, or score your current README to identify gaps.

For project-type-specific README guidance, check our open-source README guide or startup README guide.