One of the most important aspects of a software engineer/architect is to document what they have done. While it is great that they solved the problem, that solution will become a problem for someone else if the solution has not been well documented. Truthfully, I have caused my own problems when revisiting old, improperly documented code.
Why generate from the code? The simple reason is, if the documentation lives within the code, then it is more likely to be updated. Requiring a developer to jump into another repository or project takes time and can be a forgotten step in development. The more automatic your documentation is, the more likely it is to get updated.
Infrastructure as Code (IaC) is no different. Lately I have been spending some time in Terraform, and sought out a solution for documenting Terraform. terraform-docs to the rescue!
Documenting Terraform with
The Getting Started guides for
terraform-docs are pretty straight forward and allow you to generate content in a variety of different targets. All I really wanted was a simple
README.md file for my projects and any sub-modules, so I left the defaults pretty much as-is.
I typically structure my repositories with a main
terraform folder, and sub-modules under that if needed. Without any additional configuration, this command worked like a charm:
terraform-docs markdown document --output-file README.md .\terraform\ --recursive
It generated a
README.md file for my main module and all sub-modules. I played a little with configuration, mostly to set up default values in the configuration YAML file so that others could run a simpler command:
terraform-docs --output-file README.md .\terraform\ --recursive
I will get a pre-commit hook configured in my repositories to run this command before a commit to ensure the documents are always up to date.