1.2.7.1. High-Quality Terraform Module README

In the process of Terraform module development and maintenance, clear and accurate documentation is crucial for the module's usability and maintainability. This is especially true after a module is published to the Terraform Registry, as users rely primarily on the module's README.md file to obtain information via the Registry page. Therefore, writing a well-structured and detailed README is an essential part of module development.

Why is the Module README So Important?

Besides helping users understand and use the module, good documentation can also:

Help module users quickly understand the module's functionality and usage methods.
Reduce the learning curve for using and maintaining the module.
Alert users to potential risks during usage.
Do Not Hand-Write Documentation

To ensure the accuracy and consistency of the documentation, it is recommended to use the terraform-docs tool to automatically generate parts of the module content, such as input variables, output variables, and resources.

We will provide a detailed introduction to terraform-docs in a subsequent chapter, so we will not repeat those details here.

1.2.7.1.1. Recommended README Structure

A clear README.md file usually includes the following sections:

Module Introduction

Briefly describe the function and purpose of the module. For example:

## Module Name

This module is used to create and manage Azure Virtual Networks, including subnets, route tables, and other resources.

Notes

Remind users of items they need to pay attention to when using the module, such as:

Records of breaking changes included in major version updates.
Possible limitations or known issues.

Note that since this type of information cannot be extracted and annotated in the documentation by automated tools, you must explicitly highlight any changes that involve risks or require special explanation in the document.

1.2.7.1.1.1. Usage Examples

Provide at least one basic usage example to help users get started quickly:

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  name   = "my-vpc"
  cidr   = "10.0.0.0/16"
  azs    = ["us-west-1a", "us-west-1b", "us-west-1c"]
...
}

Documentation related to examples should be placed in the corresponding subdirectory within the examples/ directory. The file name should also be README.md, and it should also be generated using automated tools.

Input Variables

List all input variables supported by the module, including names, types, default values, and descriptions. This section can be automatically generated using terraform-docs.

Outputs

List all output variables defined by the module, including names and descriptions. This can also be automatically generated using terraform-docs.

1.2.7.1.2. Best Practices for Large-Scale Module Governance and Maintenance

To maintain documentation consistency and high quality across hundreds of modules, it is recommended to adopt the following practices:

1.2.7.1.2.1. Use Pre-commit Hooks to Automatically Generate Documentation

By configuring pre-commit hooks to run terraform-docs automatically before every code commit, you ensure that the documentation is always synchronized with the code.

1.2.7.1.2.2. Integrate Documentation Generation into CI/CD Pipelines

Add a documentation check step in the continuous integration process to ensure that every merged code change includes correctly updated documentation.

README