3 ms·

Huh, I hadn't made this connection, and it still may be a case of ad hoc ergo propter hoc. But they sure seem to go hand in hand. I think the first team on whi

Huh, I hadn't made this connection, and it still may be a case of ad hoc ergo propter hoc. But they sure seem to go hand in hand. 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.

simon_brown 7y ago
> 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 7y ago
  > 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!

simon_brown 7y ago

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