Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- > A good design doc can save you years of development time.
I only have a few years of experience in this business, but I have seen numerous cases where none of this matters. Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg. You are better off use that planning time for something else.
by fg137 - > Your perfectly drafted plan could easily be derailed by technical limitations, customer request or company reorg.
These are not guaranteed to happen. But if you don't have a plan, you will be derailed very soon and practically inevitably.
by bad_username - I would argue that the technical limitations should be considered during the creation of the design doc. In my experience, writing design docs can help me simplify the implementation because I've through through a lot of the headaches ahead of time.
But I will say I've seen many projects get ended by customer request or reorg. I think it's a cost-benefit analysis where you should consider the size of the project (and how long it will take to implement) vs. how long it will take to write the design doc. If it's a 2 day task, that is easy to change after the fact, then no need to write a design doc. But if it's a 2 month project that will have public endpoints that other teams or products will use, it likely is worth a 2-3 day design doc.
by jmaw - FYI, Lynch (the author) sells a course on making it to the front page of Hacker News: https://hitthefrontpage.com/
I used to like reading (or skimming) Lynch's articles, but seeing how he's profiting from gaming the system tarnishes it for me.
by gwbas1c - The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality.
So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.
by vjvjvjvjghv - Don't know about efficient, but there is at least two ways which seem to work OK-ish (although not all that efficient, I gahter):
* Do regular certifications. Before certification, check if the document is up to date. If not, update it.
* Share the documents to answer teammates' questions. Like with a WIKI it may turn out that the important stuff is actually missing/undocumented/outdated. This is then a good opportunity to fix the document.
by Linux-Fan - I answered this in another comment,[0] and I don't think there's widespread agreement on this, but I think design docs should be a short-term doc that lives until the design implementation is complete. I don't think design docs are the right format for a document that has to evolve alongside the code forever.by mtlynch
- I've found the design doc itself is relatively useless once it has been created, but that the act of creating the design doc is an indispensable part of the process. Spending time and getting your thoughts organized before diving into the team, the management and the editor makes a huge difference.by kbruner
- I think the design doc still has some value after it has been created. For me it almost acts like a checklist of things to be completed, and it's nice to have it in one place in bite-sized bits. My design docs will also have links to external resources and it's nice to have them in one place so I don't have to track them down later.
But I 100% agree that the majority of the value is gained in the writing of the design doc, and the decisions/tradeoffs that have to be thought through during that process. Which is why I strongly push back against suggestions of using AI to write design docs. Since delegating the writing to AI causes over half the value of the design doc to be lost.
by jmaw - 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?
by nseskin - Yeah, this is difficult.
My rule of thumb is to ask myself, "Is there a chance my reviewers would not have signed off had this been in the design doc they reviewed?" If the answer is yes, I send it out for a follow-up and explain why I had to change the design.
In my experience, the response from my reviewers is generally, "Yeah, that's fine." It's a combination of (1) the practical limitations that it's hard for them to get the whole design back into mental context to argue about it and (2) they trust that I'm taking the design seriously and have thought this through. I think occasionally, I've sent a post-approval change out and someone points out something
It's common to encounter a curveball nobody anticipated at design time, but if you just go rogue and unilaterally make design decisions, it degrades trust and undermines the review process, so I want my reviewers to know that I'm taking their feedback seriously.
by mtlynch - 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.
by Tsarp - Why is diataxis outdated; don't your engineers ever read the code? Don't you think it helps the agents too?by esafak
- Why do you think diataxis and the google guidance is outdated now?by blanched
- Referencing Joel Spolsky's article about how you should never do a rewrite is starting to feel outdated as well.by lopatin
- 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?
by zumtrotz - 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.
by randusername - 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.
by wpollock - 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.
by cowthulhu - Fun piece of trivia, Joel published one of his functional specs.[0]
As a huge fan of Joel's writing and engineering ideas, I was actually underwhelmed by his spec. It wasn't bad but it also felt like he missed a lot of opportunities to articulate design decisions to the reader more quickly or clearly.
One obvious mistake is that there's over a page (in a 20-page spec) just dedicated to coding conventions and what prefixes variable names will have. I think Joel later conceded that it was a mistake to cover naming conventions in a spec, though I can't find a link now.
[0] https://web.archive.org/web/20051028171624/https://www.joelo...
by 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.
by mtlynch - How are design docs changing in the agentic age?by verdverm
- Good read, although the document would be very lengthy if I am to write all the sections in the articles. I sometimes break down the design doc into multiple design docs.
- Manager doc : Summary(Background + Objective), User Story (Scenarios), High level architecture, open questions, task break down + timeline including other teams' tasks
- Engineering Architecture doc: Summary, Glossary, Goal (Functional + Non-functional + Non-goals), More detailed architecture & components between, open questions, tasks break down + timeline
- Engineering API / Database design doc: Similar summary + link to architecture doc. More detail information on API (eg: input params, output params, example client code) + database design (eg: database type + fields), open questions
Each doc is to be read within a single meeting. The shorter doc helps narrowing down the discussion scope.
Disclosure: I worked at Amazon where there is a typically 1 hour meeting session with the first 15-30 minutes dedicated to reading. It's probably why I multiple short docs over a single design doc. Telling people "Today, we'll read section 1,2,3,5,8 of the doc" didn't really work.
by lekhoa88 - This is good guidance, but what do you have to say about convincing your team of developers to live it out?
I've found that developers usually like writing code and avoid contributing to documentation. For some, it's actually scary because (edit: for them,) high quality writing is harder than high quality coding, and it can be avoided quite a bit.
On the project side, it's rare for the implementation and verification stages to not consume all the budget and more, and delivery creeping past the original optimistic date. So there's no time or money to spend on documentation.
The combination is that even with your great advice in hand, it's hard to navigate to really solid and comprehensive design documentation underpinning the products.
by hermitShell - So I tried this and it failed miserably.
The documentation became the bible, and although I tried to keep the design goals at the conceptual/logical level the following would happen the moment the implementation started:
1. This is ambigous the docs need updating, please refactor your design 2. This doesn't work as the doc stated why did you get this wrong 3. The requirements have changed you need to update it
The burden to get "everything right" was absolutely lumbered of me, and the document became an easy finger pointing exercise, even if blame wasn't intended by those launching the critique the burden of "owning" the doc and the consequences of the doc was real.
Now there's a good chance that I am just a shit documentation writer, I can accept that, but honestly I feel like for the vast majority of organisations this just falls into another step of the waterfall pattern, which just doesn't work.
How do you handle this? What did I miss?
- 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".
by bob1029 - Design document provides another person's view to the system. It's like coding but without the actual coding. Reviewing design/arch docs is much easier than reviewing code because all important logic presented as-is, without needing to decode back from code.by sigsergv
- > I've never experienced a situation where a software design document meaningfully improved the overall process.
If you don't have a document, then how do you make sure that internal team A and internal team B and internal team C and external vendor D and external vendor E all create the correct things so the entire system actually works?
by RaftPeople - It's mixed for me because there are certain things that I clearly think are needed. For example I'm building a custom network architecture and it's to the point where I'm using frontier models to reverse engineer game clients (while battling against the cyber safety system) for the sole purpose of validating that the network architecture I'm making is, if not "useful" (cause there's the game itself), at least different and superior. And to me the designs out there clearly are evidence of things not designed well and thought through ahead of time and instead a patchwork of hacks.
But then there are aspects I'm missing because while I've thought about the network protocol deeply, I'm not, say, a game developer who's ever gone through the whole game dev lifecycle. There's common patterns with software dev but it ain't it. There are probably so many things I have not thought about w.r.t. the whole deployment process that I'm not sure if letting AI vibe design+code it out is good or if I need to sit down and deeply work out the things I don't even know I don't know.
It's always a set of tradeoffs between things.
by sigbottle - The software development realm is bigger than web programming.by pif