Re:The Guide to Software Architecture Documentation
by specialist on Monday January 23, 2023 @11:00AM
(#34490418)
In my experience, our internal documentation had two tangible benefits.
The team explaining to itself what they were working on. That process was the value. Consensus and alignment. Akin to forging culture. The artifacts generated were ephemeral. Basically performance art.
Managing upwards. PHBs want to see pretty pictures.
The C4 model felt very comprehensive, but by being comprehensive, it failed to actually represent the salient points of the systems we were describing. Move up a layer, and you failed to capture some extremely relevant detail, move down a layer, and you had a bunch of extraneous information all over the place. In practice, most of our diagrams would be zoomed in on a handful of components, and represent other components as a kind of convenient lie. Which obviously wouldn't work if you wanted to understand the whole system at once, but that was rarely out goal when using diagrams.
I think it just felt more focused on the formalism rather than the expression, like drawing flowers according to a guide for drawing roses, and then getting into difficulties when you need tulips.