Module Documentation and Standards
You'll learn how to write clear, standardized documentation that makes your Terraform modules easy to understand and use by your team and the community.
Why Documentation Standards Matter
Think of module documentation like an instruction manual for IKEA furniture. Without clear diagrams and step-by-step directions, even simple assembly becomes frustrating. Your Terraform modules need the same clarity—users should understand what the module does, what inputs it needs, and what outputs it provides without reading through all the code.
Core Documentation Elements
Every module should include a README.md at its root with these essential sections:
Module Purpose
A brief description of what the module creates and the problem it solves. Keep it to 2-3 sentences.
Requirements
List required Terraform version, provider versions, and any external dependencies. This helps users know if they can use your module before they try.
Inputs (Variables)
Document every input variable with its name, type, description, default value (if any), and whether it's required. Follow the convention: variable_name - (Type) Description. Example: instance_type - (string) The EC2 instance type. Default: "t3.micro".
Outputs
List each output value, its type, and what data it exposes. Users rely on outputs to connect modules together, so be explicit.
Usage Example
Show a minimal working module block that demonstrates calling your module with typical values. This is often the first thing users copy.
Community Conventions
Use tools like terraform-docs to auto-generate consistent documentation from your code comments. Add description fields to all variable and output blocks—these become your inline documentation.
Key Takeaway: Well-documented modules with standardized structure and clear examples accelerate adoption, reduce support questions, and make your infrastructure code truly reusable across teams.