Documentation Is a Competitive Advantage

Most people think documentation exists to explain what has already been built. By the time someone starts writing it, the product is finished, the features are working, and the important decisions have already been made. Documentation becomes a record of the journey rather than part of the journey itself. The more projects I work on, the less convinced I am that this is the right way to think about it.

I've come to see documentation as one of the earliest stages of design because writing has a habit of exposing weaknesses that thinking alone is remarkably good at hiding. An idea can feel complete while it lives in your head, but the moment you try to explain it to someone else, the gaps begin to reveal themselves. You realise that a concept you thought was obvious depends on assumptions you never questioned, or that two principles you believed worked together are quietly pulling in different directions. What looked like confidence was often familiarity, and writing is unusually good at telling the difference.

That has changed the way I approach new projects. Instead of treating documentation as something to produce once the work is complete, I now see it as one of the tools that helps shape the work in the first place. Before building this website, we spent far more time defining its philosophy, structure, language and long-term purpose than writing code. At first glance, that probably looked like unnecessary preparation, especially when there were pages waiting to be designed and features waiting to be implemented. In practice, those documents became a framework for almost every decision that followed. Questions that would normally have required long discussions had already been answered because we had taken the time to write down not only what we wanted to build, but why it deserved to exist.

What surprised me most was that documentation didn't slow the project down. If anything, it had the opposite effect. Every principle we clarified removed another point of uncertainty during development, and every decision we documented was one less decision we needed to make again a week later. The time spent writing was repaid many times over because it reduced hesitation, prevented unnecessary revisions and gave the project a consistency that would have been much harder to achieve if everything had been decided along the way.

I think this is where many teams underestimate the value of documentation. They see it as a way of preserving knowledge for the future, when its greatest contribution is often improving the quality of decisions being made in the present. A conversation disappears as soon as it ends, and even the clearest discussion gradually changes in people's memories. A document, however, becomes something everyone can return to, question, refine and build upon. Over time, it stops being a description of the project and becomes part of the project's architecture.

Perhaps that's why I've stopped thinking of documentation as a collection of notes. Good documentation is really a collection of decisions, each one capturing a piece of reasoning that no longer needs to be rediscovered. Those decisions shape the work long before they explain it, and they often become one of the few advantages that competitors cannot simply copy by looking at the finished product.

The next time you're eager to ask how quickly something can be built, it may be worth asking a different question first: can you explain, with complete clarity, why it should exist? In my experience, the quality of the second answer usually determines the quality of the first.