DEV Community

Graham Cox
Graham Cox

Posted on

3

What makes a good software design document?

In my role at work, I do a lot of design work. Not graphical design - or our product would look awful! - but technical design. The documents that describe how to get from where we are now - with feature ABC missing, to where we want to be - with feature ABC present.

I'd like to think I'm quite good at this. But I know for a fact that I could be a lot better. We all could.

So, I ask you, when you produce, or read, these kinds of designs, what makes it good and what makes it bad? How can I do better at this?

(My own thoughts will follow in the comments later on, to avoid leading any discussions...)

Top comments (2)

Collapse
 
revskill10 profile image
Truong Hoang Dung

If you can add features/fix bugs to existing system WITHOUT modifying it, then your architecture is good, which means your technical design is good.

It's my single most important point to any library/framework/architecture i want to use in my work.

Collapse
 
tiso profile image
tiso

Do you have something that documents whole system, like those software architecture examples? Or what is your initial state?

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay