All notes
Dated archive / Max Ek

Write the README before you build

Clarity first, code second.

Dated archive · Max Ek · . Original content, reflecting the time it was written.

Here's a simple rule that will save you months of wasted work:

Write the README before you write the code.

Not as documentation. As design.

Why this works

When you write the README first, you're forced to answer:

  • What does this product do?
  • Who is it for?
  • Why would they use it?
  • How does it work?

If you can't answer these clearly in writing, you don't understand the product yet.

And if you don't understand it, how will your users?

The README as a design tool

Think of the README as a prototype. It's faster to write than code, and easier to iterate.

Start with:

  1. One-line description: "X for Y" or "Helps [person] do [thing]."
  2. The problem: What sucks today?
  3. The solution: How does your product make it better?
  4. How it works: 3-5 bullet points. Keep it simple.

If you can't explain it in 200 words, you don't have a clear product.

Example: Castwise README (before we built it)

Castwise: Turn podcasts into active learning sessions.

Problem: You listen to hours of podcasts but remember almost nothing.

Solution: Castwise sends you reflection prompts after each episode. Think about what you heard. Apply it to your life.

How it works:

  • Connect your podcast app
  • We detect when you finish an episode
  • Get 3 questions via email to reflect on
  • Your answers are saved in a personal knowledge base

This took 15 minutes to write. It gave us total clarity on what to build.

Why most people skip this

Because it feels like busywork. You want to build. You want to see the product come to life.

But clarity first, code second.

If you skip the README, you'll spend weeks building features you'll delete. You'll argue with your co-founder about scope. You'll pivot three times because you never had a clear vision.

The README is the forcing function that makes you think.

What to do with it

  1. Share it with 5 potential users. Do they get it? Do they want it?
  2. Use it as your north star. Every feature request gets checked against the README. Does it fit?
  3. Refine it as you learn. The README isn't set in stone. It evolves with the product.

The meta-point

This isn't really about READMEs. It's about writing as thinking.

Writing forces precision. It exposes fuzzy logic. It turns vague ideas into concrete plans.

If you can't write it clearly, you can't build it clearly.

What's the README for the thing you're building right now?

More notes