How to write an effective software design document

Post by RaftPeople » Mon, Sep 14, 2026, 10:49 PM UTC

cryptonector wrote: post #126

RaftPeople wrote: post #107

Earlier quoted context omitted.

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

At Sun we didn't use design docs for this. We used architecture docs instead. These were of the form of PSARC cases with materials such as: - interfaces lists, with attached commitment levels - interface contracts where interface commitment levels do not otherwise allow teams A, B, and C to use each other's interfaces. That's much better than design docs. The difference between architecture and design -at Sun anyway-…

I was thinking in terms of a broad usage of "design" which tends to match what you wrote about architecture.

Post by reddit_clone » Mon, Sep 14, 2026, 10:55 PM UTC

pinter69 wrote: post #112

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…

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.

Re: How to write an effective software design document

Re: How to write an effective software design document