In software engineering, most ideas can be implemented without writing any design document at all. This is particularly prominent in open source communities. For example, the Linux kernel has 35 million lines of code that have been written and rewritten many times over alongside 30 years of mailing list discussions. Linux wasn’t created as a result of a grandiose design document by Linus Torvalds, but it evolved organically in small increments of actual running code.

In open source and in software engineering in general, ideas are presented most of the time directly as patches that add, delete, or change specific lines of code. Those patches are not only read but also directly built, run, tested – and contested. Design and implementation are intertwined, and decisions are relatively small, quick, and done in writing.

However, this is not always the best way to evolve software. I would argue that even in open source, design documents are needed, and it would be good to see more of them being written than what is the practice today. Let’s dive into why, when, and how to write design documents.

Top-3 benefits: reducing risk, communicating intent, and growing the author’s ability to think

Design documents have three clear benefits. First of all, a design document helps to manage technical risk and organizational cost risk. If it takes several months or years to develop something, starting the process with a high-quality design document helps to map out unknown dimensions and decreases the technical risk of the idea being impossible to implement. If there is no design and something is developed right away, there is also a risk that it might be rejected after implementation by downstream users or collaborators, and thus all work put in would be wasted. This is the first benefit of design documents.

Secondly, design documents are an excellent medium to communicate the intent of the change to others. An engineering team might have stakeholders, executives, customers, maintainers of other dependent software packages, legal requirements, etc. While it’s perfectly possible to develop something without writing the design first, designing forces a clear articulation of what the idea is about and why it is needed.

Thirdly, writing documents grows the author’s ability to think. When writing, it becomes clear very quickly what parts of the idea are still vague, ambiguous, incomplete, or even misunderstood. It helps in revealing blind spots, giving ideas shape and detail, and thus increasing their quality. Dumping a part of your brain in a document, and then revisiting and restructuring those thoughts many times over will always lead to a better thought process and higher quality of outcome.

In open source, you rarely see people writing design documents or conducting formal review and approval processes. They do, however, exist, and open source developers should also practice their skills in writing design docs. A well-written design document not only conveys the merits of a great idea clearly but also shows that the author is a great thinker and fully understands what they are doing.

Why are design docs common in enterprise but rare in open source?

The above benefits are universal and benefit any type of software development. In the enterprise software setting, these additional aspects are often true, making design documents more common:

• Making the change happen requires a significant investment, potentially multiple people working full-time for an extended time. A written description of how that time will be used and what it will produce is needed to get buy-in from the authority that funds the development.
• Rolling out the change affects many other people and the software they develop and maintain. The whole change might be moot if there isn’t prior approval and commitment from the stakeholders to adapt to the change.
• The change might involve technical risks or have security considerations, and a technical plan needs to be vetted and approved by risk bearers before implementation starts to avoid major technical catastrophes.

Ad-hoc implementation may take place both in the enterprise setting and in open source, but ad-hoc is much more common in open source, as the person carrying the cost of the implementation work and the consequences is often the very same person. In contrast, in an enterprise setting, the costs and risks are carried by a larger group that needs to agree before any work starts.

Famous series of design documents in open source development

In open source communities, ideas that are too large to be put into code directly typically surface first as a mailing list discussion or in an issue tracker thread. Full-fledged design documents are rare, but they do exist, particularly in large projects. Examples include:

• Request for Comments (RFC) documents from The Internet Engineering Task Force
• Python Enhancement Proposals (PEP)
• Debian Enhancement Proposals (DEP)
• Ethereum Improvement Proposals (EIP)

When to write a design document

If in doubt, just start writing a design document. It is cheap, and you can always stop in the middle and never publish it. The mere fact that you are contemplating it is a sign that you probably have some unstructured thoughts floating around in your brain, and starting the writing process will benefit you a lot.

To decide if you should go all the way and actually finalize and publish a design document in contrast to just implementing the idea directly, consider the three benefits listed above: risk management, communicating intent, and building trust in the author’s ability. Are these benefits relevant for your idea? If so, publish a design document.

How to start a design doc: use a blank sheet of paper

If you decide to start writing a design document, don’t use a template; simply start with a blank sheet. Writing down any idea — large or small — should start with a paper where the author notes down the core idea first. Don’t start from a template, and in particular, avoid the pitfall of grandiose thoughts that lead to convoluted designs and bloated documents.

I’ve seen many times over the past 15 years the pattern of design document templates repeat, and it has never resulted in high-quality outcomes. Various design document templates, and fancy-sounding software development methodologies in general, are surely a good business for large consulting companies, but I have never seen them actually increase the quality of software development. In the best case, templates result in good-looking documents that are thin on content, but in the worst case, they massively dumb down the authors and put them in a mode where they are exonerated from all responsibility about the contents.

Just start from scratch and focus on the core idea. If you can’t express it briefly and clearly in a one-pager, you need to spend more time thinking about the core idea. Polish the idea before you even consider polishing the document.

How to finalize a design doc: expand and iterate

Only once the core idea is crisp and clear, and there is agreement to invest in it, should the work to polish the design document start. If there is a template, this is the point in time when it makes sense to start applying the template.

Having a crisp one-pager first also helps write the design document in a way that first presents the solution, and only then the motivations for the solution. If people jump directly to write the final design document, it often starts with a lengthy analysis of the problem and motivation of the solution, and only then the solution. Such a structure reflects the thought process of the author but is not a good way to structure a design document. The design doc should always start with the solution, and after that, the rest of the document exists to motivate and support the solution.

Writing out the full design document is all about constantly expanding and iterating it. To flesh out all aspects, it is good to have a list of questions and ensure that they are all addressed while working through the document:

• What is the title? If there are similar competing or earlier designs, what is the unique identifier of this specific design doc?
• Who is the author? Who is responsible for the design being good and correct?
• Who is going to implement it? Who is sponsoring or funding the design or implementation work?
• What is the status of the document? Is it, for example, just a draft, or is it pending comments or review, or has it already been approved?
• If the document is approved, who approved it and when? How is the approval tracked? Is it easy to prove what specific version of the design each approver read when giving their approval to it?
• What is the proposed solution exactly? Are there diagrams, pictures, prototypes, or others that cover the key parts of the proposed solution?
• What is the scope of the solution? Was something intentionally left out and why?
• Why should this solution be done now? What happens if it is not done at all, or if it is postponed? Are there workarounds?
• What assumptions is the design based on? What happens to those assumptions over time? Will they still hold?
• What alternative designs were considered? Why is the proposed solution the best?
• What are the known trade-offs and downsides of the proposed solution? How are those being mitigated?
• What is the work estimate and cost of the solution? What is the long-term cost and total cost of ownership?
• What is the development and testing plan? How will it be rolled out? Can the rollout be phased? Can it be rolled back if needed?
• What is the quality assurance process? How is security being reviewed and assured?
• What is the impact on performance? How does the system scale? Where are the limits of scalability? What is the maximum load to be used in load testing and benchmarking?
• How will the solution be operated, monitored, and measured?
• How is the success of the solution measured and validated? How does one know if the solution actually worked?
• When the solution is ready, how will it be documented and communicated? Are there different audiences that need different communications (e.g., internal vs external, developers vs users)?

Take your time

Designing is not fast. Authors should not expect to be able to sit down one day and write a design document. A good idea takes time to mature, several revisions of writing down to become clear, and a lot of time spent on waiting and getting feedback. For this reason, designing can’t be the main task for anybody but should be done on the side of other work. The design of the next idea should typically be in progress already while implementing the previous one.

Jeff Bezos famously wrote in the 2017 letter to shareholders:

The great memos are written and re-written, shared with colleagues who are asked to improve the work, set aside for a couple of days, and then edited again with a fresh mind. They simply can’t be done in a day or two.

― Jeff Bezos, founder of Amazon

A complete and high-quality design document takes a lot of calendar time. A good design matures like a bottle of wine. It can’t be forced to take shape quickly. Designing is like practicing wisdom – give it time.