When adding a complex new feature, how do you plane it in advance? Do you write a technical specification? What level of detail do you go into? How do you document how the new feature interacts with existing code?
If you write technical specs for an open source software, or your company is willing to make a technical spec public, I'd love to see it.
Top comments (4)
Personally, I found the C4 model pretty useful when describing a complex architecture
c4model.com/
I work mainly with microservices and this makes it way easier to understand each service as well as the global picture. It allows to go pretty deep into the implementation using the same model
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?
Programming is the art of enabling business capabilities with the least amount of code.
This is what Dan North explains in his "Software, Faster" book I warmly recommend to read: leanpub.com/softwarefaster