why i build small

I used to start projects by drawing the whole thing first. Every folder, every abstraction, every edge case I could imagine. It felt productive. It was mostly procrastination with a diagram.

the smallest thing that works

Now I write the version that barely works, and I ship it. This site is a good example. It started as one page with my name on it. No blog, no tags, no mascot. Just a name on a cream background.

Everything since has been one small step on top of something that already ran.

why it holds up

The trick is that a working thing tells you the truth. A diagram doesn’t. You find out that the abstraction you were so proud of has exactly one caller, and that the edge case you spent an hour on never happens.

# the version I would have written first, planning for callers who never came
class ThoughtRepository(Generic[T]):  # T bound to Persistable
    def __init__(self, adapter: StorageAdapter[T]) -> None:
        self._adapter = adapter


# the version that actually shipped
posts = list(Path("content/thoughts").glob("*.md"))

The second one is not clever. That’s the point. I can read it in six months without reconstructing what past me was worried about.

the part that’s hard

Building small means showing people things that aren’t finished, which I still find uncomfortable. But an unfinished thing that exists beats a perfect thing that’s still a diagram in my notes app.

Start small. Keep it running. Add one thing.