Course contentsShow
← Cloud and Infrastructure
Lesson 717 of 2,98913. Infrastructure as Code FoundationsFree lesson

Documentation and Comments

Learn when and how to document IaC code, including inline comments and external documentation practices.

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.