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

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

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