docs-writer

name

docs-writer

description

Regenerate and validate the provider's Terraform Registry documentation, add Example Usage / Import examples for a resource, or author a guide (getting started, authentication, or a vN→vN+1 migration guide). Use this whenever the task touches `docs/`, `templates/`, or `examples/` — e.g. "regenerate the docs", "the docs CI is failing", "add an example for signoz_<name>", "write the dashboard migration guide", or after adding/registering a resource (docs are schema-driven and must be regenerated). Docs are a generated byproduct of the schema + examples + templates — never hand-edit files under `docs/`.

Provider documentation

Docs under docs/ are 100% generated by terraform-plugin-docs (tfplugindocs) from three inputs: the live provider schema, the templates/, and the examples/. Never hand-edit docs/*.md — edits get overwritten on the next go generate.

The one rule: schema is the single source of truth

Every template ends with {{ .SchemaMarkdown | trimspace }}. Do not restate the schema as hand-written ### Required / ### Optional lists — they drift (we shipped http_timeout (Number) docs after the arg became a duration string). Override a template only when a resource needs extra prose; otherwise let the default template handle it. This is the DataDog model: a sparse templates/ with a single override for one genuinely complex resource, everything else on the default template — never a template that restates the schema.

Regenerate

Run the deterministic script — scripts/regen-docs.sh:

bash .claude/skills/docs-writer/scripts/regen-docs.sh   # needs `terraform` on PATH

It runs go generate ./... from the repo root, which generate.go wires to two //go:generate steps, then validates:

1. terraform fmt -recursive ./examples/
2. tfplugindocs generate -provider-name signoz -rendered-provider-name SigNoz

This re-renders all docs. After adding one resource's examples, git status should show only that resource's new docs/**/<name>.md (+ example files) — the other docs/*.md re-render byte-identical.

Examples layout (what the default template discovers)

examples/
  provider/provider.tf
  resources/signoz_<name>/resource.tf          # → ## Example Usage
  resources/signoz_<name>/resource_<variant>.tf # extra blocks, filename-sorted
  resources/signoz_<name>/import.sh             # → ## Import (CLI)
  data-sources/signoz_<name>/data-source.tf

Keep examples minimal-but-valid (required attrs only for resource.tf). The default template embeds every resource*.tf as its own block, filename-sorted — use an underscore suffix for variants (resource_minimal.tf) so resource.tf sorts first (_ > .; - would sort before .).

The registry groups the left-nav by the subcategory: frontmatter field (the AWS scale lesson). The default template emits subcategory: ""; setting it needs a per-resource template or skaff support — forward-looking, few resources today.

Guides (long-form prose → Registry "Guides")

Guides live in templates/guides/*.md.tmpl and render to docs/guides/. They are Go text/template — escape literal {{ }} inside code blocks. Existing: v0.0.11-to-v0.0.12, v0.0.x-to-v0.1.0, migrate-signoz-alert-to-signoz-rule.

Migration guides (vN→vN+1)

Lead with import {} + terraform plan -generate-config-out (Terraform 1.5+): Terraform writes the typed HCL from refreshed state, so users don't hand-translate opaque jsonencode(...) blobs. Do not build a bespoke JSON→HCL converter. Full approach, the provider survey, and the honest caveats to document: references/guide.md.

Gate (must pass before merge)

CI (.github/workflows/docsci.yml) runs three checks — go generate ./..., a drift diff (git diff --exit-code), then tfplugindocs validate. Reproduce them locally with CHECK=1:

CHECK=1 bash .claude/skills/docs-writer/scripts/regen-docs.sh

validate (publishability: frontmatter, size, schema↔doc parity) and the drift diff (freshness) catch different failures — both must be green.

Note on generated resources

skaff-emitted schemas carry no Description, so generated resources render with blank attribute docs. That's a known gap with an upstream fix (emit Description from the OpenAPI spec). Don't paper over it with hand-written schema lists in a template.