Introduction
Never in my wildest dreams as an engineer did I think I would get to the point where I valued documentation and READMEs above the code itself. But that day has arrived!
This post will be short and sweet blog post on the value of terraform-docs. With a couple of insights into how this fantastic tool has been implemented at almost every organistaion I’ve worked in to simplify documentation standards for Terraform Modules as well as reduce workload on engineers.
What is it?
terraform-docs is a utility used to generate documentation from Terraform modules in a standardised format that can be replicated at scale across every module repository in your organisation.
As you can see below it focuses on providing easy to read and important values out of your terraform module in order to inform on how to configure and customise inputs as required.
The focus on the key elements such as requirements, providers, inputs and outputs as well as the option of including examples has been nailed by terraform-docs.
The Value
Documentation, Documentation, Documentation, was a statement repeated to me in my early years of infrastructure engineering as one of the most important skills you can posses. I often questioned this but it has become abundantly clear to me in the last few years the true value of good documentation is undeniable.
Thoughtful Engineering
The process of thinking through an end-to-end solution and writing out the steps required, rather than just building it is a skill that many engineers haven’t spent the time to perfect over their career.
The act of systematically thinking through and documenting the steps required for an end-to-end solution is a skill that goes beyond mere execution. It involves a deeper level of understanding and consideration for various components of the system. Much like the concept of rubber duck debugging, where explaining the code to an inanimate object helps identify issues, writing out the steps of a solution forces you to articulate and clarify your thought process. It not only benefits others who may need to understand or contribute to the solution but also enhances your own comprehension.
This approach is akin to creating a roadmap for your project. By breaking down the solution into individual steps, you gain a clearer perspective on the intricacies involved. It’s a form of mental simulation, allowing you to anticipate challenges, dependencies, and potential improvements before diving into the actual implementation. Importantly, it’s a form of simulation that is from a different perspective other than your own enabling potential scenarios originally not envisioned.
In a collaborative environment, this skill becomes even more valuable, as it facilitates knowledge transfer, accelerates onboarding for new team members, and establishes a comprehensive reference for future work. Additionally, the act of documenting the steps often reveals insights and optimizations that might be overlooked during the initial conceptualization.
In essence, this disciplined and deliberate approach to problem-solving, documented step-by-step, not only serves as a guide for others but becomes a powerful tool for your own continuous learning and improvement as an engineer.
Time Saving
In a world where many of my days are spent in YAML or Markdown files, any tool that streamlines the process becomes a valuable asset. The automation capabilities of Terraform Docs, especially through pre-commit hooks and GitHub Actions, are game-changers. By integrating these automation mechanisms into your workflow, you not only save time but also ensure consistency and standardization in your documentation. This is particularly crucial in collaborative environments and large-scale projects where maintaining a unified look and feel across documentation is essential.
The result is a constant and reliable experience for your engineering team. Engineers can confidently consume and contribute to Terraform modules without being bogged down by manual documentation formatting, leading to increased productivity and a more enjoyable development experience.
Pre-Commit Hooks
Git pre-commit hooks are scripts that run before the actual commit is made. They provide a way to enforce certain checks or conditions before allowing a commit to be applied to the repository. This ensures that the committed code adheres to specific standards or passes predefined tests. Pre-commit hooks are local to each developer’s machine and are not distributed with the repository.
In our use case of terraform-docs pre-commit hooks provide a proactive approach, ensuring that documentation is formatted correctly before any code is committed. This helps catch issues early in the development process, preventing inconsistencies from being introduced into the codebase.
terraform-docs even provide a guide on how to setup a pre-commit hooks.
More broadly speaking there is a fantastic pre-commit for terraform by Anton Babenko, highly recommend you review this for adoption as well.
GitHub Actions
GitHub Actions is an automation and CI/CD service provided by GitHub. It allows you to automate various workflows, including building, testing, and deploying your code directly from your GitHub repository. GitHub Actions is integrated into the GitHub platform, making it easy to set up and manage automation for your software development projects.
GitHub Actions take this a step further by automating the documentation generation process. This not only saves time for developers but also ensures that the documentation is updated in sync with code changes. It contributes to a seamless and standardized experience for engineers consuming the modules, enhancing clarity and reducing the learning curve.
Similarly, for GitHub Actions terraform-docs provide a guide for enabling this in your GitHub.
Final Thoughts
terraform-docs is one of my favourite tools in the terraform ecosystem, providing a high return on investment of time. Enabling documentation through code for peers and consumers of your terraform modules without the hassle of formatting markdown tables consistently.
If you haven’t started using terraform-docs, the sooner the better!