[tetha]

To me, there is also the question of change frequency. Of course, it's a guesstimate all the time, but things that look to be rarely-changing (and usually ends up being high-impact) deserve over-documentation. Something like our AWS VPC, DNS and DHCP setups and their expected change modes and their effects are very well documented. It rarely changes and if it breaks, everything breaks. The fundamentals of our disk setups and disk encryption in ansible is carefully documented because if that breaks, things will go hairy.

In those cases, having a lot of documentation, speeds up changes because you can store months and years of deliberation and decisions in these comments.