Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to write an effective software design document

refactoringenglish.com

Post reply on HN
Print view View original

11–20 of 132 posts

Re: How to write an effective software design document

#11

Post by felixgallo »

bob1029 wrote: post #10

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 offsh…

You have successfully optimized for fast, but you have not optimized for quality, extensibility, customer experience, or maintainability. Fast can be a great thing to optimize for, but there are many other situations where other optimizations are preferable.

Re: How to write an effective software design document

#12

Post by mtlynch »

mjr00 wrote: post #5

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 tha…

OP here.

Thanks for reading and for the thoughtful feedback!

> Only real criticism I have here, is I would not include any code in a design doc, unless it is really really vitally important.;

Yeah, that's fair. If I were setting guidelines for a large org, I'd maybe discourage code snippets in design docs, as it's hard to know when is too much. At my last company, the dev team was just 3-4 people, and I found it helpful to have little snippets in design docs especially when we're talking about semantics of a new library or how to migrate existing code to a new system.

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

Yeah, I agree this could change with LLMs, but I think Joel is still correct up to today. Bun is an interesting case because it's friendliest possible conditions for an LLM rewrite (self-contained inputs and outputs, easy to test old implementation and new implementation side by side, huge test corpus w/ third-party tests). I haven't followed it closely, but it seems like the jury's still kind of out as to whether the rewrite was a good idea.

Re: How to write an effective software design document

#13

Post by 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.

Re: How to write an effective software design document

#14

Post by verdverm »

mtlynch wrote: post #3

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.

How are design docs changing in the agentic age?

Re: How to write an effective software design document

#15

Post by fmbb »

felixgallo wrote: post #11
bob1029 wrote: post #10

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 offsh…

You have successfully optimized for fast, but you have not optimized for quality, extensibility, customer experience, or maintainability. Fast can be a great thing to optimize for, but there are many other situations where other optimizations are preferable.

> you have not optimized for quality, extensibility, customer experience, or maintainability

A ”software design” document does not optimize for either of those.

Re: How to write an effective software design document

#16

Post by tobyjsullivan »

bob1029 wrote: post #10

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 offsh…

It sounds like you’re defining design as UI/UX design. I think most people include (prioritize, even) things like system architecture, performance bounds, etc.

Re: How to write an effective software design document

#17

Post by 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?

Re: How to write an effective software design document

#18

Post by phuff »

felixgallo wrote: post #11
bob1029 wrote: post #10

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 offsh…

You have successfully optimized for fast, but you have not optimized for quality, extensibility, customer experience, or maintainability. Fast can be a great thing to optimize for, but there are many other situations where other optimizations are preferable.

Welcome both of you to the agile vs waterfall arguments of 25+ years ago. :)

The agilists I think ended up having pretty good answers for finding a sweet spot between small iterations that maintained quality while minimizing Big Design Upfront to prevent spending a lot of time preplanning the software, allowing a well functioning agile team to maintain reasonably high quality, extensibility, maintainability and satisfaction of actual customer needs while keeping velocity high and not getting bogged down in design heavy tar pits which were ended up not fully anticipating problems encountered during actual execution.

If that doesn't sound like a buzzword filled sentence I never expected to come out my mouth... But. The bottom line is: if you can keep your execution goals small and focused enough, you can iterate quickly towards a design with better information than you would have if you were to do a design study because you'll be better informed by the actual needs of the execution process than by what you _think_ the execution process will require at design time.

Re: How to write an effective software design document

#19

Post by 1over137 »

bob1029 wrote: post #10

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 offsh…

Software is in nuclear plants, cars, oil platforms, pacemakers, everywhere. If one is writing more ‘disposable’ stuff like flashlight apps for smartphones, then sure, as you say. Others are writing serious stuff, and design docs are invaluable.
Post reply on HN