Writing Documentation

This page is the house style for the CAPTF book, which lives in this repository under src and is published at https://captf.io/docs/. Every page follows it, and make verify enforces the parts a tool can check.

Where things go

The book is split by reader and by page type. Pick the section by who reads the page, then the page type by what they need.

Every fact lives on exactly one page. Other pages link to it instead of restating it. The page that owns a topic is the one whose title names it; when two pages could own a fact, the more specific one does.

Generated pages

These pages under reference/ are generated from code and must not be edited by hand:

• api.md, by crd-ref-docs from the Go types in api/v1alpha1;
• conditions.md, events.md, alerts.md, manager-flags.md, runner-cli.md, tfcapi-lint-cli.md, environment.md, annotations-labels.md, clusterctl-variables.md and make-targets.md, by internal/docsgen;
• metrics.md, by internal/metrics.

Each starts with a “Generated by” comment. Generated prose comes from single-line Go doc comments and usage strings, where wrapping would mean rewrapping source text, so each generated page also carries a <!-- markdownlint-disable MD013 --> directive, ahead of the “Generated by” comment so it also covers that comment’s own line, that scopes the line-length rule off for that page only; every other Markdown rule still applies to generated pages.

These pages, and the contract schemas under module-author/contract/v1alpha1/schemas, are generated from a checkout of the provider repository (cluster-api-provider-terraform), not from anything in this repository. To change one, change the code or the Go doc comment it comes from there, then run make docs-gen DOCS_DIR=<path to this checkout> from the provider repository to rewrite the pages here. make verify-docs DOCS_DIR=<path to this checkout>, also run from the provider repository, fails when a generated page, schema copy or example is stale; this repository’s own make verify does not check staleness, since it has no access to the provider repository’s source.

Hand-written pages link to the generated ones for field lists, flags, reasons, events, metrics and keys, and never copy those tables.

Page shape

• One H1, the page title, matching its SUMMARY.md entry.
• A first paragraph that says what the page covers and who it is for.
• For how-to pages and runbooks: a “Before you begin” list of prerequisites, then numbered steps, then how to confirm it worked.
• A closing “See also” list when related pages exist.
• Headings in sentence case: “Rotate the credentials”, not “Rotate The Credentials”. SUMMARY.md entries use title case.
• Heading text stays stable once published, since links and alert runbook_urls point at the anchors derived from it.

Voice and wording

• Address the reader as “you”. Use the present tense and the active voice.
• Say what happens, not what “should” happen. Reserve MUST, MUST NOT, SHOULD and MAY (RFC 2119, in capitals) for the normative module contract.
• American English: behavior, labeled, license, canceled.
• “CAPTF” is the project. Spell out “Cluster API Provider Terraform (CAPTF)” on the introduction page only.
• “Terraform or OpenTofu” in prose; terraform and tofu in code for the command-line tools. “OpenTofu” is always written with a capital O and T.
• Kinds use their exact names in code spans on first mention in a section: TerraformCluster, TerraformMachine, TerraformMachinePool, their *Template kinds, and TerraformClusterIdentity. In running prose, “machine pool” is fine.
• Expand an abbreviation on first use on each page: KubeadmControlPlane (KCP).
• No references to source files, functions or line numbers on Getting Started, User Guide or Operator Guide pages. Describe the behavior. Module Author and Developer Guide pages may name source files when the reader needs them.
• No § section references. Link to the heading instead.
• No dates, review notes, “TODO”, “pending” or “planned” statements. State what is true now. If something does not exist yet, say that it does not exist.

Markdown

• Wrap prose at 80 columns. Tables, code blocks and headings are exempt.
• Fence every code block with a language: sh, yaml, hcl, json, text.
• Shell examples show commands only, without a $ prompt, and use <angle-bracket> placeholders the reader replaces. Explain each placeholder below the block.
• Outside fenced code blocks, a placeholder always goes in a code span: `<namespace>`. A bare <name> in prose or a table cell is read as an HTML tag, and make verify-book fails on it.
• Tables use the compact style: | a | b | with a | --- | separator row.
• Link to other book pages with relative links to the .md file, including the anchor when you mean a section: [drift](../concepts/drift-and-health.md#drift).
• Link to files in the provider repository with a full https://github.com/captf-io/cluster-api-provider-terraform/blob/main/... URL. Relative links must not leave this repository’s src.
• Include real files instead of pasting them, with a path relative to the page: {{#include examples/Containerfile.opentofu}} on a page next to the examples/ directory.
• Diagrams are Mermaid code blocks, rendered by mdbook-mermaid.

Checks

In this repository, make verify runs:

The provider repository checks this book’s generated content against its own source, from a checkout of this repository passed as DOCS_DIR: make verify-docs DOCS_DIR=<path> (generated pages, contract schemas and examples) and make docs-check (that every https://captf.io/docs/ URL named in the provider repository’s code and Markdown resolves to a page and heading here). Neither is part of this repository’s own make verify.

Preview the book with make serve and open http://localhost:3001.