Has anyone tried using terraform-docs to auto-generate the "why" comments? Seems like it could help with the transparency thing but I haven't tested it in production.
Automation regret: I scripted myself out of understanding my own stack
srelet
Member
DragonMark said:
Terraform-docs
It generates "what" beautifully. "Why" requires human judgment. We tried enforcing it in CI: PR rejected if no `## Rationale` header in module README. Compliance was 40% and the other 60% wrote "because we need it." Waste of review cycles.
Better to have one person own the narrative and rotate that role.
srelet said:
One person own the narrative
Bus factor of one. Same problem, different wrapper.
I started writing a decision log in `docs/adr/` for this client. Architecture Decision Records, one per major module choice. "We chose three NAT gateways because X, accept tradeoff Y." At least when I google my own variable names I find the reasoning.
YuriDavid
Member
I keep ADRs too but mine are all "tabs because spaces caused the divorce" level of useful. The format matters less than actually returning to read them.
indentation is not optional
Following this thread. I have 47 terraform modules and I know maybe 8 of them properly. Going to try the ADR thing and the runbook debt list. Not sure I have the discipline for both but even one would be an improvement.