What makes a good software design document?

twitter logo github logo ・1 min read

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...)

twitter logo DISCUSS (2)
markdown guide

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.


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

Classic DEV Post from Nov 28 '19

New browser on the block!

Graham Cox profile image