What makes a good software design document?

grahamcox82 profile image Graham Cox ・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...)


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?