DEV Community

Discussion on: (How) do you write technical specifications when adding complex new features?

emgsilva profile image
Eduardo da Silva

I also like C4 for "initial architecture/design". However, as the project evolves in time we need to make design decisions (sometimes complex, sometimes simpler). To write/keep-track of those I really like to use the ADR (Architecture Decision Records) framework, by Michael Nygard ( This framework allows to document decisions that we take as the project evolves in time. It makes a very comprehensive set of questions, namely: context, decision, consequences, etc. In a nutshell it touches the "why", "what" and "how" of a decision - and implications. A decision should(read "must") be treated as "immutable", i.e.: you do not change it. A change to a decision is treated as another decision, i.e.: a new ADR. The ADRs are normally kept on the code base of the project (i.e.: we version control them like any other artifact of our software product), which makes it really good to trace the "major" design decision within the project and also as a documentation.

Few months ago I wrote about this topic (and also motivation for developers to more systematically think about their architecture/design decisions - for which ARD is just a tool). You can read it here:

mgan59 profile image
Morgan Craft

Eduardo, I'm a huge fan of ADRs would love to chat. Best place to message you?