HN

Comments (96)

• lefra
  Coming from an optics/electronics background, it's fascinating to see how much debate there is here around whether a design document is useful or not. I don't think any engineer outside software would start a project without writing at least a few paragraphs to make sure everyone agrees on what needs to be built, and that there's no major blocker.I blame the low cost of iteration in the software world (even lower now with LLMs).
• Menu

  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".
• Menu

  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.
• Menu

  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.
• 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?
• Menu

  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.
• 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.
• Menu

  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?
• fg137
  > 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 any 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.
• kbruner
  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.
• Menu

  vjvjvjvjghv
  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.
• esposito
  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.
• HyperL0gi
  I think specs are incredibly valuable for who's writing/developing the software as a thought exercise, and pretty much useless for anyone else, especially after you ship it as it'll always get outdated very quickly.
• Menu

  baalimago
  Isn't much of this made redundant by being part of an existing system? Also, this level of detail is a recipe for being outdated once the issues and compromises starts coming in
• Menu

  jimbobimbo
  My problem recently is to have people read design docs I'm writing.
• bcrosby95
  I've never been much for design docs. But I have some projects that are on again/off again and I can lose my train of thought. It seems like having one of these could help a lot with that.
• Menu

  acrophiliac
  Some of the items in your document seem more like non-functional requirements that I would expect to find in a specification, not a design document,e.g., security, privacy, legal.
• acrophiliac
  Some items in your doc seem more like non-functional requirements that I would expect to see in a specification, not a design document: e.g., security, privacy, legal.
• Kuyawa
  > A good design doc can save you years of development timeBrainstorm with your agent in a new session, ask a thousand questions, at the end ask for a detailed prompt.md to develop an app then tell it to complyThere, saved years of development time in AI era
• Menu

  mjr00
  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 sectionOnly 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
• Menu

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

  0xbadcafebee
  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.
• maschiojv
  [flagged]
• Menu

  gbrindisi
  Claude, write a skill to create design docs as per this blog post /sIn 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?