Writing a good design document

> The goal of a design document is to convince the reader the design is optimal given the situation.

This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient.

Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptable tradeoffs. Where multiple reasonable alternatives exist, they should be make explicit along with a justification for why one option was chosen over the others.

Will it be perfect? Probably not, unless it is an easy problem or you over-designed. And even if it's a good design, it can hit unforeseen issues during implementation. The goal of design is not to eliminate all possibility of such issues but to mitigate risks and communicate to the stakeholders what we're building and why we're building it that way.

The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals.

Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements.

As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot.

The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved?

I've been in companies that do this. I like it more than alternatives.

The default for most meetings everywhere I've seen is to present information during the meeting, verbally or in powerpoint. For example, standups often devolve to people sharing their updates. This is much worse than having people write down updates and taking a few minutes to read them at the beginning.

Also note that these documents usually take about 5 minutes to read, even for slow readers. Meetings with much longer documents are pretty rare in my experience - feedback on long documents is usually done separately.

It would theoretically be better for people to read the documents ahead of time. But the benefit is pretty small IMO, and the cost is large – it fails if even a single person hasn't read the document.

Isn’t “making acceptable tradeoffs” (optimization) while “meeting requirements & constraints” (under constraints) simply optimization under constraints? I fail to see how this is about sufficient _but not optimal_ solutions.

I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others.

However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?