How to write an effective software design document • Hacker News Board

Re: How to write an effective software design document

#141

Post by anonymous2024 » Tue, Sep 15, 2026, 9:13 AM UTC

harrouet wrote: post #139

mtlynch wrote: post #27

Earlier quoted context omitted.

OP here! I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons: 1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, re…

I am on the design-doc team and I'd like to add the 3rd category: 3. The developer is not able to imagine how the design works because s/he has no capability for abstraction. Needs to go hands-on. I might add that writing the doc is not the purpose, the purpose is to think it, challenge it and share it.

The design "doc" is needed, but not the static doc for printers, a more dynamic one where you don't need a 50 pages doc with lots of links between pages, but a very good dynamic diagram with some text.

Re: How to write an effective software design document

#142

Post by bluefirebrand » Tue, Sep 15, 2026, 11:55 AM UTC

mtlynch wrote: post #27

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…

OP here! I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons: 1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, re…

My experiences has been

3. The business cannot figure out a direction so the developer can either churn on design docs fruitlessly or make prototypes that visually show the business people what our options are in order for them to make up their minds

Re: How to write an effective software design document

#143

Post by sigsergv » Tue, Sep 15, 2026, 2:02 PM UTC

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…

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.

Re: How to write an effective software design document

#144

Post by munksbeer » Tue, Sep 15, 2026, 2:31 PM UTC

reddit_clone wrote: post #132

pinter69 wrote: post #112

Earlier quoted context omitted.

Num. 2 especially relatable. A good mark of high quality professional is if he presents his plan before execution to hear feedback and comments - even if they are totally against his original idea, and he can then take this feedback and incorporate effectively in a re-design.

This does not always work. Often, the group members presented to, do not have the required knowledge to critique the design document. I have seen people proposing (demanding even) changes based on vague feelings and their need to be seen as contributing. Once they say something, it is out there, now it is the poor presenter who has to refute it or accept modifications to the design.

If they don't have the required knowledge before coding, how are they going to have the required knowledge if you skip the design and just hand them the finished code?