End User Documentation

Code Structure

All end user documentation is found in the /website folder of the repository.

├── website/docs
│   ├── actions/               # Documentation for actions
│   ├── d/                     # Documentation for data sources
│   ├── ephemeral-resources/   # Documentation for ephemeral resources
│   ├── function/              # Documentation for provider functions
│   ├── guides/                # Long format guides for provider level configuration or provider upgrades
│   ├── index.html.markdown    # Home page and all provider level documentation, including provider configuration
│   ├── list-resources/        # Documentation for list resources
│   └── r/                     # Documentation for resources
└── examples/                  # Large example configurations

Guidelines

Follow these guidelines to keep provider documentation consistent. Unless noted otherwise, resource refers to resources, data sources, list resources, ephemeral resources and provider functions.

Examples

Each resource must include at least one example Terraform configuration.

• Examples must be functional.
• Examples that includes several resource definitions should be added to the repository examples directory instead of an individual resource documentation page. Each directory under examples should be self-contained; if a user run terraform plan on the example, no errors should be returned.
• Terraform configuration should use terraform code fences. Do not use hcl code fences.
• Examples should not define terraform or provider blocks.
• Examples should refrain from highlighting particular Terraform configuration language syntax workarounds or features such as variable, local, count, and built-in functions.
• Generally the resource instance name should simply be example, e.g. resource "aws_instance" "example".
• All name arguments within the example configuration should use simple example values that match the resource being defined. Where attribute validation allows, prefer values prefixed with example-, e.g. name = "example-instance". Avoid overly complex naming.
• Examples do not need to include every argument. A basic example should use the same configuration as the resource's basic acceptance test.

Arguments

Every argument must be documented.

Ordering

In documentation, the order of arguments is:

1. Any arguments that make up the resource's identity.
2. Required arguments, sorted alphabetically.
3. Optional arguments, sorted alphabetically.

Bylines

Valid bylines are:

• "This resource supports the following arguments:" if required and optional arguments are in one list, or
• "The following arguments are required:" and "The following arguments are optional:" if required and optional arguments are split into separate lists.

Description

Every argument must have a description.

• Descriptions are concise and follow US English spelling and grammar rules.
• Descriptions start with a verb or noun — never "A ", "An ", "The ", "Specifies ", "Indicates ".
• Boolean argument descriptions start with "Whether to ".
• Don't spell out common abbreviations. See Abbreviations below.
• Information about AWS service features and valid argument values that are likely to update over time should link to AWS service user guides and API references where possible.
• If an argument has validation allowing only specific inputs, these must be documented. For example:
  • Allowed values are: `value1`, `value2`, and `value3`..
  • Valid value is between `0` and `100`.
• If the argument has a default value, this must be documented, e.g. Default value: `ENABLED`..

Blocks

Each block argument must have two entries in the documentation:

1. The initial entry, with a link to the subsection describing the block's arguments. e.g. `ip_rule` - (Optional) IP rules. See [`ip_rule` Block](#ip_rule-block) below..
2. A subsection, added after all top-level arguments. If the resource has multiple blocks, these subsections should be ordered alphabetically.

Within the subsection, arguments follow the ordering rules above. Additionally any Computed attributes are listed alphabetically after any Optional arguments.

For example:

## Argument Reference

* `name` - (Required) Name of the thing.
* `ip_rule` - (Optional) IP rules. See [`ip_rule` Block](#ip_rule-block) below.

### `ip_rule` Block

The `ip_rule` block supports:

* `ip_range` - (Required) IP range of the rule.
* `description` - (Optional) Description of the rule.
* `status` - (Computed) Status of the rule.

Attributes

Every attribute must be documented.

Ordering

In documentation, the order of attributes is:

1. Any id attribute
2. The remaining attributes, sorted alphabetically.

Bylines

Valid bylines are:

• "In addition to all arguments above, the following attributes are exported:", or
• "This resource exports no additional attributes." if no attributes are exported.

Description

Every attribute must have a description.

• Descriptions are concise and follow US English spelling and grammar rules.
• Valid values and default values are not documented.
• Don't spell out common abbreviations. See Abbreviations below.

Blocks

Each block attribute must have two entries in the documentation:

1. The initial entry, with a link to the subsection describing the block's attributes. e.g. `health` - Health status. See [`health`](#health) below..
2. A subsection, added after all top-level arguments. If the resource has multiple blocks, these subsections should be ordered alphabetically.

Within the subsection, arguments follow the ordering rules above.

For example:

## Attribute Reference

This resource exports the following attributes in addition to the arguments above:

* `id` - ID of the thing.
* `health` - Health status. See [`health`](#health) below.

### `health`

`health` supports:

* `status_code` - Health status code.
* `status_message` - Health status message.

Abbreviations

Don't spell out an abbreviation in a description if the abbreviation has effectively become a lexical item — a term readers understand directly rather than by expanding it. Spelling it out can make documentation less readable without improving understanding.

For example, a typical reader understands "ARN" directly; expanding it to "Amazon Resource Name" does not help them understand the concept.

Test for treating an abbreviation this way: Does spelling it out materially improve the intended reader's understanding? If not, use the abbreviation.

This applies to argument and attribute descriptions, as well as general prose (e.g. the resource description, Note blocks). It does not apply to the first use of a term that a typical reader of AWS provider documentation would not already recognize.

Abbreviations to use instead of spelling out (swissshepherd's banned_glosses check enforces this list; see .ci/swissshepherd-weak.hcl):

Notes

Notes provide information beyond the basic description of a resource, argument or attribute. Notes follow the format ((->|~>|!>) **Note:**). Level of importance is documented below.

Informational Note

Provides additional useful information, recommendations and/or tips to the user.

Use the -> **Note:** format. The Terraform registry will template this note as a block with an info icon.

For example:

-> **Note:** The `activation_code` argument cannot be imported.

Warning Note

Provides information that the user will need to avoid certain errors. These errors are non-breaking and do not cause irreversable changes.

Use the ~> **Note:** format. The Terraform registry will template this note as a block with a warning icon.

For example:

~> **Note:** All arguments including the username and password will be stored in the raw state as plain-text.

Caution Note

Provides critical information on potential irreversible changes, including data loss and other negative effects.

Use the !> **Note:** format. The Terraform registry will template this note as a block with a caution icon.

For example:

!> **Note:** This will destroy and recreate the table, possibly resulting in data loss.