The design doc that saves years: a Google and Microsoft veteran's playbook
How to Write an Effective Software Design Document
A good design doc forces you to think through hard decisions before wasting time on the wrong implementation. Drawing on experience at Google, Microsoft, and his own companies, Michael Lynch explains when a design doc is worth writing, how much to invest, and which sections matter. The core rule: include a decision only if getting it wrong is costly. He also shares a real example design doc for a web app.
A good design doc can save you years of development time.
- bob1029
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".
- mtlynch
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.
- wpollock
Two suggestions, based on my experience:
1) Add a section called "Potential Changes". This is broader than "missing features", and can include other items too, such as new hardware that might become avaliable, customer requirement changes you might anticipate, possible new technology (e.g. a new database or cloud service that might be useful), multilingual support, etc. Listing some of these often causes reviewers to think of others as well.
Ensuring the design is modular around such changes means implementing any of them will be far easier than if assumptions are hard-coded throughout the codebase.
2) Security and privacy are two aspects of a more general category of "compliance assurance". Those two are worthy of their own categories, but you should have a section covering any other legal, regulatory, or corporate requirements. The plan for auditing these compliances should be listed too.
Often, of course, there are none beyond security and privacy.
- randusername
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.
- zumtrotz
Sorry for being pedantic.
It reads more like a CONOPS or a software architecture document, but its not detailed enough from a high level perspective, and too detailed at a low level perspective (ie. it has implementation details in a few places you wouldnt expect in a higher level design doc).
In that light, I'm not sure who the audience would be in a corporate environment. Is it for architects, other developers, or yourself?
- Tsarp
Lot of this is outdated. Including stuff that made a lot of sense in the past like diataxis and the google guidance.
I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill.
I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. This with a simple cli to help parse this has made the docs experience much quicker and nicer.
You can also generate svgs, mermaids etc on the fly now when you are really stuck on something.
- cowthulhu
I was initially turned on to the idea of using specs by Joel Spolsky [https://www.joelonsoftware.com/2000/10/02/painless-functiona...]
I think they're valuable, both because they get you to think through the actual functionality (and underlying implementation) of the software, and the make sure that you and the [person you're developing for] are roughly on the same page. Plus, every edge case or design issue you catch while writing the spec saves you a ton of time.
That said, I think a big weakness of specs is that it's just not possible to write a perfect spec that doesn't have any blind spots and covers all the edge cases and issues you'll run into when actually developing. This makes it more difficult to hold the customer accountable to the spec, since you (the designer and devs) can't really be accountable to the spec unless you want to deliver some overly literal, not-actually-helpful product.
- nseskin
I’m curious how you handle design docs when requirements change significantly during implementation. At some point, updates and corrections can start describing a somewhat different project from the one that originally went through review.
Is there a rule of thumb for when it’s enough to update the existing document, and when the design has changed enough to justify a new design doc and another review?