re: (How) do you write technical specifications when adding complex new features? VIEW POST


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 (thinkrelevance.com/blog/2011/11/15...). 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: esilva.net/everyone-architects/sto...


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

code of conduct - report abuse