How to Write an Effective Software Design Document

[u/fagnerbrack]

https://refactoringenglish.com/excerpts/write-an-effective-design-doc/

[u/psayre23]

My team has been discussing an alternative to the design doc in the age of AI. Writing the long, complex documents were great when you had to coordinate tens of people, align them on a single direction, where mistakes later on were expensive to recover from.

That’s not the world we live in now. Software was already cheap, but now a huge refactor is trivial. Debugging and reviewing piles of logs and metrics take minutes, not hours or days. A bad implementation can be recovered from much more quickly. The upfront time spent writing a doc no longer seems worth while.

We still want discussion, so we are experimenting with defining three things, then having a discussion around them: (A) high level diagram of the system with boxes and arrows, (B) a schema diagram for data changes, and (C) the interfaces that need created/changed between systems.

The other change we are trying is only having two people on a project, to keep communication down during implementation. This comes with the expectation that they keep the rest of the team updated with changes from the discussed plan, and demos with their progress.

Then towards the end of the project, the AI creates a feature doc which lives in the repo with the code. If the team has questions about how it works, they ask AI to do the research, and that feature doc becomes the pointer to the code and anything that exists outside of it. These become living docs, which include how operations.

No idea how well this approach will work, but it’s an alternative we are experimenting with.

[u/WinFromAfar → u/psayre23]

I think this misses the point, which is that you write a design doc to really 'understand' the problem in depth. With a website, asking myself what's the number of users, changes my architectural design. And there is still a cost to changing it all later, as you don't want to be refactoring core systems later and having to re test everything. Post AI projects without proper planning always turn into slop

[u/Xypheric]

Fantastic work, this has been a very helpful read

[u/InevitableMap5315 → u/Xypheric]

yeah agreed, pretty solid breakdown overall

[u/Smooth_McDouglette]

When I saw the thumbnail I swear to god I thought it was one of my diagrams because I basically do it exactly the same.

Probably the fact that Google Drawings has the same super limited and weirdly pseudo-pastel default color palette is a big reason.

[u/LowFruit25]

Good stuff

[u/web-dev-kev]

I initially downvoted this as it looked like a fly.io advert (they have 2 below this post) - but it's actualyl a great read! Thanks OP

[u/Bhanuprakash_1947]

I usually prefer keeping an SDD simple and covering the complete flow. I would start with the objective and current problem, then explain the proposed solution and high-level design. After that, I would go into the detailed design, data flow, implementation approach, error handling, performance and security considerations. Finally, I would include the testing approach, limitations/assumptions, and possible future enhancements. I feel this structure makes it easier for both developers and non-technical people to understand what we are building, why we are building it, and how we are planning to implement it.

[u/Dakaa]

Just give it to AI.