This message was deleted.

the beauty of HCL + Terraform is that it is, in general, self-documenting 🙂 I like to call it "executable documentation" for my infrastructure. If you are doing non best practice things such as using local/remote execs, then it is good practice to call out the reason for using these in a comment. There is also this tool, which is pretty useful: https://terraform-docs.io/

Yeah, I’d subscribe with the use of terraform-docs. However, I’ve seen that usually proper

descriptions

attributes are either ignored, or just overlooked. When those attributes (either for input variables, but also, for output values) are properly described, enriched with enough information and guidance looking for clear “interfaces” and an easy understanding (E.g.: declaring explicitly what’s required, values allowed, validations that are applied, links to references for official docs, or to the Terraform registry docs that belongs to the specific resource being created, etc.), the automation/generation of the docs is the easy part 😉 And, as @Thomas Harris mentioned — clear code in a way that resource blocks are concisely named, also helps!

take a look at Terramate 🙂 https://github.com/mineiros-io/terramate