Provider Docs

# Copyright IBM Corp. 2025, 2026
# SPDX-License-Identifier: MPL-2.0

interface:
  display_name: "Terraform Provider Docs"
  short_description: "Best practices for Terraform provider docs"
  default_prompt: "Use $terraform-provider-docs to create or update Terraform Registry provider documentation with HashiCorp-aligned structure and style."


# HashiCorp Provider Documentation Reference

Source of truth for this skill:
- https://developer.hashicorp.com/terraform/registry/providers/docs

## Core Rules

- Publish provider docs through Terraform Registry using `tfplugindocs`.
- Generate provider docs from schema descriptions and markdown templates.
- Store templates under the repository `docs/` directory with expected naming conventions.
- Keep release tags and manifest metadata valid so Registry can render and display docs.

## Template Paths

Use these template paths when the corresponding provider objects exist:

- `docs/index.md.tmpl`
- `docs/data-sources/<name>.md.tmpl`
- `docs/resources/<name>.md.tmpl`
- `docs/ephemeral-resources/<name>.md.tmpl`
- `docs/list-resources/<name>.md.tmpl`
- `docs/functions/<name>.md.tmpl`
- `docs/guides/<name>.md.tmpl`

## Generation Workflow

HashiCorp recommends wiring generator execution through `go generate`:

```go
//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
```

Run from repository root:

```bash
go generate ./...
```

Alternative direct execution:

```bash
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
```

## Release and Publication Constraints

- Use semantic version tags prefixed with `v`.
- Create tags from the default branch.
- Keep `terraform-registry-manifest.json` in the repository root.
- Understand docs appear by provider version in Registry once the provider release is published.

## Preview and Troubleshooting

- Use HashiCorp's preview process to verify rendering before release when needed.
- If docs are missing or stale in Registry, verify:
  - tag naming and tag branch source
  - manifest file presence and validity
  - provider version publication state

## Related Canonical Pages

- Provider docs guidance:
  - https://developer.hashicorp.com/terraform/registry/providers/docs
- Terraform Plugin Docs (`tfplugindocs`) source and usage:
  - https://github.com/hashicorp/terraform-plugin-docs


---
name: provider-docs
description: Create, update, and review Terraform provider documentation for Terraform Registry using HashiCorp-recommended patterns, tfplugindocs templates, and schema descriptions. Use when adding or changing provider configuration, resources, data sources, ephemeral resources, list resources, functions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation.
---

# Terraform Provider Docs

## Follow This Workflow

1. Confirm scope and documentation targets.
- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
- Decide whether content should come from schema descriptions, templates, or both.

2. Write schema descriptions first.
- Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
- Keep wording specific to argument purpose, constraints, defaults, and computed behavior.

3. Add or update template files in `docs/`.
- Create only files that map to implemented provider objects.
- Use HashiCorp-recommended template paths:
  - `docs/index.md.tmpl`
  - `docs/data-sources/<name>.md.tmpl`
  - `docs/resources/<name>.md.tmpl`
  - `docs/ephemeral-resources/<name>.md.tmpl`
  - `docs/list-resources/<name>.md.tmpl`
  - `docs/functions/<name>.md.tmpl`
  - `docs/guides/<name>.md.tmpl`
- Keep templates focused on overview and examples; rely on generated sections for field-by-field details.

4. Generate documentation with `tfplugindocs`.
- Prefer repo