README-Driven Development — Write the Docs First, Code Second

Most developers write their README as an afterthought — a chore to tick off before shipping. README-Driven Development (RDD) flips this: write the README first, then build the thing it describes.

It sounds backwards. It's not. Here's why it works.

The problem with code-first

When you start coding before documenting, you make decisions in the wrong order. You build an API surface, then try to explain it. If the explanation is awkward, the API is awkward — but by then you've already built it.

Code-first projects also suffer from scope creep. Without a written spec of what you're building, “just one more feature” is irresistible. A README acts as a contract with yourself.

How RDD works

Step 1: Write the README

Before writing a single line of code, write a complete README for the finished product. Include:

• What the project does (one line)
• Why someone would use it (the problem)
• Installation instructions
• Usage examples with actual code
• API reference if applicable
• Configuration options

This forces you to think about the user experience before the implementation. How will someone install this? What does the API look like? What's the simplest possible quick start?

Step 2: Get feedback

Share the README with a colleague or potential user. Can they understand what the project does? Do the code examples make sense? Is anything confusing?

Getting feedback on a README is cheaper than getting feedback on code. Rewriting a paragraph takes seconds. Refactoring an API takes days.

Step 3: Build what you documented

Now build the project. Your README is your spec. Every code example in the README should work exactly as written. If you find yourself wanting to change the API, update the README first and check whether the new version is actually better.

What RDD catches early

• Bad naming — If a function name is hard to explain in the README, it's a bad name. Rename it before you write it.
• Too many steps — If your quick start is 12 steps, your setup is too complex. Simplify before building.
• Missing use cases — Writing usage examples reveals scenarios you haven't considered. Better to find them now than after launch.
• Scope creep — If it's not in the README, it's not in v1. The README defines the boundary.

When to use RDD

RDD works best for:

• Libraries and packages (where the API surface matters most)
• CLI tools (where the user experience is the interface)
• New projects where scope isn't yet defined
• Open-source projects that need contributor buy-in

It's less useful for internal tools where you're the only user, or for rapid prototypes that might be thrown away.

The Tom Preston-Werner origin

RDD was coined by Tom Preston-Werner (GitHub co-founder) in 2010. His argument: “A perfect implementation of the wrong specification is worthless.” The README forces you to get the specification right before investing in implementation.

Sixteen years later, the principle is more relevant than ever. With AI code generation, implementation is cheap. Getting the spec right is the hard part.