How to Write an Effective Software Design Document

Author here. Happy to take any feedback about this post.

I learned to write design docs at Microsoft and Google, and I thought they both had good culture around docs that hasn't percolated out as well as other engineering practices at those orgs. I haven't seen a thorough explanation of how to write design docs, so this is my attempt to externalize what I've learned about writing them.

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long.

It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offshore oil platform. You do not need to prove a whole lot of things in advance of construction. No one actually has to give you permission to do anything. You can email a link of a vertical slice prototype to the business whenever you feel like it. That can be the "design document".

No feedback on the design doc, except to say it's a good template and very helpful for someone who hasn't worked in a world where design docs have been critical. But can I say we use tinybeans and have a similar complaint (and others), and we would happily jump ship if there was an alternative like that laid out in your example.

I have worked on DO-178C (aerospace) and IEC 62304 (medical device) software design documents and they are much narrower in scope.

OP's design document is comprehensive enough to cover much of ground of the full documentation package for regulated software submissions. Basically all that's left is tracing requirements to design to verification method to verification result.

These are some great tips! I have some notes:

- One of the things about design you notice as you get older, is the bigger a software application is, the worse your options are later on. The design doc can be considered a proxy for the application: the bigger your design doc, the bigger the application will be. You should still try to think about as much of the app as you can in your design doc (don't intentionally try to make it small and miss things). But if you start to notice this doc is getting pretty heavy, that may be a hint that the application is trying to do too much.

- Next suggestion: make C4 diagrams and split up your design doc by each level. You don't need to make perfect C4s, or even have a good handle on how to define them. You just need four levels of abstraction by which you'll give the reader a picture of how your application works and fits into larger concepts. This will help you and the reviewers understand it better, and will likely also elicit more questions, which helps you better define the design.

Example C4 layout:

  SLAs & SLOs
    - Interfaces & Logging
      - Monitoring, Alerting
      - Dependencies
    - Security / Privacy / Legal
    - Infrastructure

SLOs encompass everything else because they're the objective of your product/service/application. Monitoring & Alerting comes from the Interfaces & Logging because the purpose of the Monitoring & Alerting is to "consume" your Interfaces & Logging, in order to meet your SLOs. Security / Privacy / Legal are under SLOs because the extent to which you perform all those things again comes from SLAs (which are basically a bunch of SLOs combined with legal stuff). Infrastructure comes from SLOs because you can't meet your SLOs/SLAs without Infrastructure built to fit them.

My problem recently is to have people read design docs I'm writing.

Really nice read. I'll add that it's effective to scope design docs up and down as needed, both in terms of how big your project is and how big your company is. A 50-person startup doesn't need a full design doc with multiple approvers. But a one-pager explaining what you're doing and having some documentation is really helpful even with an engineering team of 5. I'll also still write design docs for code changes that only touch a handful of files, if I feel it's important enough. The process of writing in a concise and precise way for other people to consume also has the positive side effect of making things more clear for yourself, too.

> Interfaces section

Only real criticism I have here, is I would not include any code in a design doc, unless it is really really vitally important. I've seen a lot of design docs (especially in the LLM age, written by more junior staff) which are effectively just an English summary of code. The point of a design doc is (generally) not to explain that you're going to have a WidgetManager and WidgetFactory class and what specific properties and methods they have, it's to explain how the widget creation workflow works and maybe you have the WidgetManager/WidgetFactory in an architecture diagram. As a general rule, if you're starting to include actual code, you've gone too low-level, IMO.

> Not all design decisions are equally important. Some choices are more permanent than others.

At AWS one of the corporate culture memes was calling a decision either a "one-way door" or "two-way door". Just asking yourself the question, if we had to walk this back, is it truly irreversible or just an inconvenience? Turns out most day-to-day decisions are two-way doors, particularly engineering ones. Even if the choice made is wrong and a bunch of work needs to be done to switch back, it's still preferable to what a lot of companies end up in, which is decision paralysis where every change needs approval from multiple committees, resulting in months or years before work can start. Note that this doesn't meaningfully increase the odds the decisions made are the right ones; it just delays the implementation and diffuses responsibility if the wrong decision was made.

> A from-scratch rewrite would never work, and even if you manage to write new code in Rails, you’re still maintaining code in two wildly different languages.

Orthogonal to the article, but this line of thinking (including the link to the classic 2000 "Things You Should Never Do, Part I" article[0]) may be worth reviewing in the post-LLM world; for all their flaws, LLMs are spectacular at language-to-language translation, and we already have one major project released[1] that shows porting a relatively large and mature project from one language to another is possible. Not to say that it's the best use of your time, or that you shouldn't do your due diligence and pick the right language up front, or even that the original 2000 article was about a language-to-language rewrite (the Netscape rewrite was an architectural redesign).

[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-...

[1] https://bun.com/blog/bun-in-rust

it would not be "fun" to financially penalize my coworkers for their mistakes, no.

Claude, write a skill to create design docs as per this blog post /s

In all seriousness a big chunk of my work is reviewing docs and 100% of the design docs I read these days are generated and there is a lot of slop. I have to parse them with AI to make sense of them, contributing to the problem. I wish people would follow a sensible set of rules like this one.

Did anyone have any solution to this dread? Or cracked the code on how to write docs that have other agents as their primary audience?