Terraform module registry documentation: what a consumer sees, and what is missing from it

Inputs, outputs, providers, and required versions come out of the source automatically, on the registry page and in a README section if you run terraform-docs. Hand-maintaining any of that is wasted effort, and a module whose input table is stale is usually a module whose maintainer edited the table instead of the code.

The gap is the same everywhere: a consumer reading the module page can tell what they may pass in and cannot tell what they will get. Usage examples help with the first question, not the second. A module that creates a bucket, a key, a service account, and three IAM bindings looks, from the input table, exactly like a module that creates a bucket.

Module repositories are structurally odd, and the convention makes them so. HashiCorp's Standard Module Structure puts examples of using the module under examples/ at the root, so the only directories that qualify as root modules are usually the demos. Naive analysis draws them and calls it a day, which produces a diagram of example code rather than of the module.

Datadef sets aside directories whose path contains a segment reading as examples, tests, fixtures, e2e, wrappers, or ci. When those are the only root modules, the referenced module with the most resources is promoted to be the subject instead. A module that accounts for more than half of everything visible in the repository also earns a deeper budget, sixteen drawn nodes rather than the eight a module gets when it is one component among many, because compressing the subject of the repository into eight boxes would hide the thing being documented.

Module documentation has a versioning problem that repository documentation does not. Consumers pin to v5.8.1 and read the page for v5.8.1, so a diagram generated from main is wrong for most of the people looking at it.

A Datadef project is bound to a repository plus a branch or a tag, so connect the tag. The project synced from v5.8.1 keeps showing the v5.8.1 architecture, and a new release gets its own connection. Put the live embed line in the README of that tag and the module page carries a picture that matches the code the consumer is actually calling.

One markdown image line is the whole integration, it renders in the registry and in GitHub, GitLab, or Azure DevOps alike, and no account is needed to view it. Mermaid is the usual alternative and it has the opposite trade-off: it renders natively in some hosts and not others, and somebody has to hand-edit it every time the module changes.

# terraform-google-secure-bucket

![What this module builds](https://datadef.io/api/embed/secure-bucket-a1b2c3d4)

## Usage

```hcl
module "bucket" {
  source  = "acme/secure-bucket/google"
  version = "5.8.1"
  name    = "analytics-raw"
}
```

<!-- terraform-docs inputs and outputs below -->

One sentence saying what the module owns. The picture. The smallest working usage example, because that is the block people copy. Then the generated input and output tables. Then the notes that no generator can produce: what the module deliberately does not create, which inputs are load-bearing for security, and what a caller has to provision first.

That last group is the highest-value prose in module documentation and the part most often missing, because it is the only part that requires a decision rather than a command. For the repository-level version of the same argument, see the Terraform documentation generator.

• Terraform module versions and dependencies
• Terraform documentation generator
• Embed diagrams in a GitHub README
• Live embeds: one markdown line