[simon_brown]

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

[sixstringtheory]

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