How I Documented My Terraform DevSecOps Project

Documenting a Terraform DevSecOps project effectively combines automated documentation, clear architecture visualization, and reproducible setup instructions—mirroring real-world DevOps practices where clarity, consistency, and collaboration are critical. Using tools like terraform-docs, you can automatically generate and maintain up-to-date READMEs, while integrating diagrams and step-by-step guides ensures onboarding and audits are seamless.

****Tools

Terraform CLI
terraform-docs (installed locally or in CI)
Markdown editor
Diagramming tool (e.g., Lucidchart, Draw.io, or Excalidraw)
GitHub or similar repo platform 

****Step-by-step instructions

• Install terraform-docs using a package manager (e.g., choco install terraform-docs on Windows, brew install terraform-docs on macOS, or download from terraform-docs GitHub)

• Organize your Terraform project with clear module structure (e.g., main.tf, variables.tf, outputs.tf)

• Write descriptive comments for variables, outputs, and resources using the description field

• Create a .terraform-docs.yml configuration file in the project root to define the README structure:
  

version: "1"
sections:
  show:
    - requirements
    - providers
    - inputs
    - outputs
    - resources
content: |
  # {{ .Escape .Name }}
  {{ if .Has .Content }}{{ .Content }}{{ end }}

  {{ if .Has .Requirements }}## Requirements{{ .Requirements }}{{ end }}
  {{ if .Has .Providers }}## Providers{{ .Providers }}{{ end }}
  {{ if .Has .Modules }}## Modules{{ .Modules }}{{ end }}
  {{ if .Has .Inputs }}## Inputs{{ .Inputs }}{{ end }}
  {{ if .Has .Outputs }}## Outputs{{ .Outputs }}{{ end }}
  {{ if .Has .Resources }}## Resources{{ .Resources }}{{ end }}

• Run terraform-docs markdown table --output-file README.md . to auto-generate the documentation block inside README.md.

• Manually add sections above or below the auto-generated content:
  

- 
Project Title and Description
- 
Architecture Flow (embed or link a diagram showing CI/CD pipeline, IaC flow, security gates)
- 
Setup Instructions:
    Clone the repo
    Run terraform init
    Run terraform plan to review changes
    Run terraform apply to deploy

- 
DevSecOps Integration Notes (e.g., Checkov for static analysis, GitHub Actions for CI/CD)

- 
Commit both .terraform-docs.yml and updated README.md to version control
(Optional) Set up a GitHub Action to auto-update the README on pull requests:

name: Generate Terraform Docs
on:
pull_request:
branches: [ main ]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Generate README.md with terraform-docs
uses: terraform-docs/gh-actions@v1.0.0
with:
output-file: README.md
output-method: inject
git-push: "true"