• Examples and Terraform modules should contain documentation explaining features and how to use them.

• Links on the Terraform Registry web-site are relevant and will not work, so use absolute paths in README.md.

• Documentation may include diagrams created with mermaid and blueprints created with cloudcraft.co.

• Use Terraform pre-commit hooks to make sure that the code is valid, properly formatted and automatically documented before it is pushed to git and reviewed by human.

Documentation

Automatically generated documentation

​pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. It is written in Python and is a powerful tool to do something automatically on developer's machine before code is committed to git repository. Normally, it is used run linters and format code (see supported hooks).

With Terraform configurations pre-commit can be used to format and validate code, as well as to update documentation.

Check out pre-commit-terraform repository to familiarize yourself with it, and existing repositories (eg, terraform-aws-vpc) where this is used already.

terraform-docs

​terraform-docs is a tool which does generation of documentation from Terraform modules in various output formats. You can run it manually (without pre-commit hooks), or using pre-commit-terraform hooks to get documentation updated automatically.

Resources

1. ​pre-commit framework homepage​

2. ​Collection of git hooks for Terraform to be used with pre-commit framework​

3. Blog post by Dean Wilson: pre-commit hooks and terraform - a safety net for your repositories​