This is tragic and too common, in my experience.
It's like code should document itself but it rarely does. And then we're back to transmitting oral knowledge to every new hire.
I think the first team on which I ever experienced Agile– working on a CAD program–was quite good with documentation. Ever since then–about 8 years–it's been almost all bad. All my work since then has been on iOS, so I maybe difference in domains has something to do with it too.
I often say code should "document itself," but I guess what I really mean is that the code should be readable and understandable, without obfuscating elements like anonymous identifiers, single letter variables etc, or needing comments explaining _how_. Comments should explain higher-order ideas like _why_. But, no one part of code can document the whole _system_ to which it belongs, nor can e.g. Git commit logs (which I also highly value). For that, I absolutely need diagrams and technical writing.
Yes, that's exactly why I use the maps analogy when describing the C4 model. If you were teleported into a random part of the country where you live, you'd find it very time consuming to figure out where you are, and where you want to go. The maps on your smart phone allow you to zoom-out and get some context.
It's the same with code. If you join a team with a million lines of code, simply exploring the code to figure out what's going on is an incredibly time consuming exercise. The diagrams and technical writing provide some zoomed-out context, so you can better explore the codebase.
The trick, of course, is to not document everything. Travel guidebooks don't explain everything about the place you're visiting, only the highlights. Software documentation should do the same.
This makes a lot of sense to me, I think I would do well to remember it, thanks!
I don’t think it’s complete but I think I see more documentation and diagrams so it out automatically from projects than the stuff that was consciously written by librarians or tech writers (or created as a result of following a CASE tool or Rational’s UML stuff).
I have seen far fewer garbage diagrams that confused. If I had to choose between a pretty diagram and a hacked up json file that describes relationships, I’d take the semistructured data any day. I can always write a graph viz on top of the data that is always in sync, but it’s really expensive to try to spit out data from a graphic.