Writing a good design document

Post by j45 » Thu, Aug 14, 2025, 7:08 PM UTC

nickm12 wrote: post #141

barrystaes wrote: post #127

Earlier quoted context omitted.

This + Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated screenshots so everyone quickly sees what we are talking about. Layer two also lists alternative solutions considered and why not chosen. Layer three is developers making a few notes on chosen tech design, most important is the choice reasoning here. In all layers, add and use references. Less is more,…

Yes, agree with all of that. I don't think every design doc needs every possible section, but if readers would benefit from the background or the an enumeration of stakeholders, that belongs up front, before the design.

Definitely - some sections are a bare minimum while others get activated based on complexity or need.

Post by xmprt » Wed, Aug 20, 2025, 5:28 PM UTC

tremon wrote: post #149

nickm12 wrote: post #64

The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals. Each…

I usually work on infrastructure as code, and I usually swap out the third layer of the design for the first layer of the implementation. You need a fully-specced functional design and a high-level technical design, but I've found that in many cases the technical implementation details can change as the project is developed, and that means either the low-level technical design and the implementation go out of sync, o…

I see the third section as more of a feasibility assessment and for people to comment on whether the technical design is sufficient and extensible or to look for alternatives. It's ok if the design diverges from the implementation but I'd still look for it in a design review so people can point out any flaws or security/scalability issues proactively.

Re: Writing a good design document

Re: Writing a good design document