Documentation Driven Development

I had this idea in my head before LLMs existed. Like my Clean Code styleguide, I believe code needs to be mostly understandable in what it does and why, and I see that as important as the code itself. That layer makes it way faster to navigate a codebase and understand what is going on, what the expected inputs and outputs are, even before you look at the function.

I'm talking about docstrings. I'm a huge fan of docstrings in functions, classes, and file headers. For me they turn code into human language.

Documentation Driven Development means documentation is a main artifact next to the code, not an afterthought. You write it before and after. It's not just comments for the machine, it's the explanation for the human.

Then AI made this a much bigger thing. Because now, for coding assistance, you need context engineering. So I don't just write docstrings to capture my intent anymore, I keep a whole docs/ folder for everything that needs and deserves to be documented about a project.

I call this Documentation Driven Development because it shows you how everything works, what the ideas and decisions were. That makes code way easier to understand than just the lines of code.

Doing it manually at the start of my career showed me how good an investment this is. When you share code and everything is already explained, or you come back to a codebase after a few months and can jump right back in, because everything you need to know before reading the code is already there.

That's the idea. And maybe code won't be the important part in the future. Maybe the docs are the real work of a software engineer, and the code just accompanies them.

Want to see how I actually organize my docs/ folder? That's the next post.