Skip to content

Role Documentation

Every role gets a section on this site, and every section follows the same structure so a reader always knows where to look. The governing principle: the usage guide is brief and quickly useful — someone deploying a role they've deployed before should find the command they need in seconds, and someone new should learn what must exist first without wading through reference material. Everything deeper lives in linked pages within the same section.

The policy side — that a usage guide is mandatory, ships in the same PR as the change it documents, and stays in sync with meta/argument_specs.yml and CLAUDE.md — lives in the Development Standards. This page is the structure those docs follow.

Section layout

Role sections live under the Roles entry in the nav, one subsection per role, named after the role. Each section contains:

Page Required Content
Usage Guide always Requirements, prerequisites, and the canonical commands — structure below
Tags and Variables when the role has tags or configurable variables (nearly always) The combined reference: tag table + variable reference
Sample Configurations when configurations differ by scenario One page per named scenario with a complete, copyable variable set
Role-specific pages as needed Deep dives that would bloat the usage guide — e.g. Kuiper's API reference, Perimeter Auth's firewall configuration, Certificate Authority's per-backend guides

File conventions: docs/roles/<role>/usage-guide.md, docs/roles/<role>/tags-and-variables.md, docs/roles/<role>/sample-configurations/<scenario>.md — the directory mirrors the nav. New pages are added to the nav: in mkdocs.yml, and mkdocs build --strict must pass before the change is done (see Documentation).

Existing sections predate the docs/roles/ layout

Sections created before this standard live directly under docs/<role>/ and are grouped under Roles in the nav only. They move to docs/roles/<role>/ individually, as part of the same migrate-when-touched policy described below — moving a section changes its URLs, so each move should update every inbound link and go through its own PR.

The usage guide

Sections in this order. If a topic outgrows a screenful, move it to its own page in the section and link it — the guide links out rather than growing.

1. Requirements

Everything that must be installed or reachable for the role to run, as a table. Write None explicitly rather than omitting the section — an absent section is ambiguous, an explicit None is an answer.

  • Collections and roles the control node needs. List them as prerequisites without dictating how they're installed.
  • Network/URL access the control node or target needs — github.com, PyPI, the PowerShell Gallery, package repositories (e.g. nginx.org), download hosts. Be exact: customers build egress allowlists directly from this list, and a missing entry surfaces as a mid-deploy timeout at a customer site.

2. Prerequisites

Environment state that must already exist before the role runs — as distinct from software the control node needs. Other roles that must run first (with links to their usage guides), certificates that must be issued, accounts that must exist, files the customer must provide, required variables that have no defaults. Use an ordered list when the order matters. None explicitly if empty.

3. Usage

The canonical invocation, and at most two or three variants — not one per tag. Real commands with the standard shape (--limit, --become, -e @extra_vars/...), annotated with when each extra-vars file is actually needed. Long commands get { .force-wrap } on the code fence. Point at the Tags and Variables page for everything else.

The Tags and Variables page

One combined reference page — tags and variables interrelate too tightly to split, and one page keeps the section navigable:

  • Tags: a table of tag(s) → task file → what it does. State the role's tag-gating behavior up front (fails fast without an intent tag, or runs everything by default).
  • Variables: grouped by functional area, each with required/optional, default, and what it controls. Don't transcribe meta/argument_specs.yml wholesale — the argument spec is the authoritative machine-checked reference (ansible-doc -t role <name>); this page adds meaning, context, and short examples the spec can't carry.
  • Secret-bearing variables document both shapes — lowercase Ansible var and uppercase environment fallback — using the tabbed === "Environment Variables" / === "Ansible Variables" blocks, per Secret Management.

Sample Configurations

One page per named scenario (e.g. "Linux (PRD)", "SQL Install Only — No Database Automation"), each containing a complete, copyable variable set for that scenario with a sentence or two of context: what the scenario is and what it assumes. These replace inline "Sample Variables" sections in usage guides — a sample that lives in the guide bloats it and hides from the nav.

Family sections

Roles that ship and run as a unit — the four storage roles (aws_linux_storage, azure_linux_storage, aws_windows_storage, azure_windows_storage) are the model — share a single section named after the family rather than four near-identical ones. The same structure applies, plus a short page listing the member roles with links to their repositories. This is a sanctioned pattern, not an exception.

Playbook sections

Some sections document playbooks rather than a single role (Active Directory, gMSA). The same structure applies where it fits: a brief usage guide with requirements, prerequisites, and canonical commands, with reference material split out the same way.

Migration

This standard applies to new roles immediately. Existing sections migrate when touched — if a change lands in a section's docs, bring the pages you touch fully up to this structure rather than patching the old shape (that includes renaming a "Templates" subsection to Sample Configurations, folding a usage guide's tag table into the Tags and Variables page, and moving the section from docs/<role>/ to docs/roles/<role>/). Don't launch a standalone retrofit of everything at once.

Reference examples today: kuiper/usage-guide.md for the guide shape, microsoft-sql/tags-and-variables.md for the combined reference page.