hashicorp Review: End-User Documentation
Assume the @maintainer persona. Scope: resource docs (r/), data source docs (d/), list resource docs (list/) under website/docs/, rendered at the Terraform Registry. Loaded from review-pr.
Authoritative reference: docs/end-user-documentation.md. When this skill and that document disagree, the document wins. Do not review CHANGELOG updates.
Should the PR include docs?
- If the PR adds or changes user-facing behavior (new resource/data source/attribute) but has no doc change, say what's missing.
- If the PR removes behavior but leaves stale docs, say what to remove.
- Review only the changed docs; don't review unchanged documentation except as needed for context.
Description openings
The single-line description: in frontmatter and the first paragraph after the H1 must use the verb for the doc type:
| Doc type | Opening verb |
|---|---|
| Resource | Manages … |
| Data source | Provides details about … |
| List resource | Lists … |
Flag openings like "This resource…", "Use this resource…", "Allows you to…", "Resource for…", or "Terraform resource for…".
Argument and attribute description style
Forbidden opening words: An, A, The, Defines, Indicates, Specifies. Rewrite "Indicates the amount of storage" → "Amount of storage." Always propose the corrected wording.
Don't spell out common abbreviations (e.g. "Amazon Resource Name (ARN)" → "ARN"). See Abbreviations for the full list and rationale.
Boolean arguments must start with Whether to:
- ✓
(Optional) Whether to enable logging. - ✗
(Optional) Enables logging./(Optional) If true, enables logging.
(Required) / (Optional) / (Read-Only) are the only valid markers, capitalized in parentheses, immediately after the hyphen.
Examples use example, not test. Flag any HCL block in docs that uses "test" as a resource label or name = "test".
Section structure
Resource docs, in this order:
# Resource: <aws_resource_name>## Example Usage(with at least### Basic Usage)## Argument Reference## Attribute Reference## Timeouts(only if the resource exposes timeouts)## Import(only for resources)
Data source and list resource docs have only Example Usage, Argument Reference, and Attribute Reference.
Argument Reference
Required arguments come first, separated from optional by a header line. Alphabetize. Use these exact lead-ins:
The following arguments are required:
* `req_arg` - (Required) ...
The following arguments are optional:
* `opt_arg` - (Optional) ...
If there are no required arguments, drop the "required" subsection — don't write "There are no required arguments."
For tagged resources, tags lives under optional arguments with this exact wording:
* `tags` - (Optional) Map of tags assigned to the resource. If configured with a provider [`default_tags` configuration block](/docs/providers/aws/index.html#default_tags-configuration-block) present, tags with matching keys will overwrite those defined at the provider-level.
Attribute Reference
Open with This resource exports the following attributes in addition to the arguments above: (substitute "data source" / "list resource"). Flag pages that re-document arguments here — only computed attributes belong. Alphabetize.
For tagged resources, tags_all has this exact wording:
* `tags_all` - Map of tags assigned to the resource, including those inherited from the provider [`default_tags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block).
For tagged data sources, tags is a top-level computed attribute and there is no tags_all.
Code fences
Use terraform for .tf blocks and console for shell examples. Flag hcl (use terraform) or unfenced shell commands.
Style points
- Active voice, present tense. Don't document past or future behavior.
- Single-line description in frontmatter — flag multi-paragraph descriptions.
- Consistent terminology — match the AWS service's nouns; don't invent synonyms.
Import section & Identity Schema
The ## Import section (resources only) and its Identity Schema subsection have a precise required structure. See references/import-section.md for the full checklist and load it when the PR touches a resource's Import section.