Documentation and Comments
What You'll Learn
You'll learn when and how to document your Infrastructure as Code, using inline comments and external documentation to make your infrastructure clear and maintainable.
Why Documentation Matters in IaC
Infrastructure code is read far more often than it's written. When you or a teammate returns to an IaC file six months later, good documentation explains why decisions were made, not just what the code does. Think of it like leaving breadcrumbs for your future self—or notes for a colleague inheriting your infrastructure.
Inline Comments
Use inline comments to explain:
- Non-obvious decisions: Why you chose a specific instance size or unusual configuration
- Workarounds: Temporary solutions or vendor-specific quirks
- Security or compliance rationale: Why certain restrictions exist
- Complex expressions: When logic isn't immediately clear
Keep comments concise and focused on the "why," not restating what the code already shows. Avoid comments that simply repeat variable names.
External Documentation
Beyond inline comments, maintain external documentation:
- README files: Overview of what infrastructure the code provisions, prerequisites, and how to use it
- Architecture diagrams: Visual representation of resource relationships
- Runbooks: Step-by-step operational procedures for common tasks
- Change logs: Track major infrastructure changes and their rationale
External docs should live in version control alongside your code, ensuring they evolve together.
When to Document
Document when:
- The reasoning isn't obvious from the code alone
- You're implementing organization-specific patterns
- Future modifications might break something important
- Compliance or security requirements drive decisions
Don't document obvious variable assignments or standard patterns—let the code speak for itself there.
Key Takeaway: Good IaC documentation combines targeted inline comments explaining why decisions were made with external documentation providing context, architecture, and operational guidance—all version-controlled with your infrastructure code.