# How-To — Template

Use for step-by-step runbooks. Each step is one concrete action with the
expected result.

## Sections

- Title — verb-first ("Configure TLS on the staging cluster", not "TLS
  Configuration")
- Prerequisites (what must already be true before starting)
- Steps (numbered, one action per step, with the expected output)
- Verification (the single check that proves the change worked)
- Troubleshooting (top 3 things that go wrong, with their fixes)
- Related (links to sister how-tos and the owning team page)

## Anti-patterns

- Don't write steps that require a human to interpret them. "Configure the
  cluster" is not a step.
- Don't bury the verification at the end of the page. Put it where the reader
  will see it after step 1.
- Don't use screenshots where commands work. Screenshots go out of date;
  commands don't.

## Storage template

```xml
<h1>{Verb-first title}</h1>
<p>{One sentence: what this how-to does and when to use it.}</p>

<h2>Prerequisites</h2>
<ul>
  <li>{what must already be true}</li>
</ul>

<h2>Steps</h2>
<ol>
  <li>
    <p>{action}</p>
    <p><em>Expected output:</em></p>
    <ac:structured-macro ac:name="code">
      <ac:parameter ac:name="language">bash</ac:parameter>
      <ac:plain-text-body><![CDATA[{expected output}]]></ac:plain-text-body>
    </ac:structured-macro>
  </li>
</ol>

<h2>Verification</h2>
<p>{Single check that proves the change worked. If it fails, the rest of the
how-to doesn't apply.}</p>

<h2>Troubleshooting</h2>
<table>
  <tbody>
    <tr>
      <th>Symptom</th>
      <th>Cause</th>
      <th>Fix</th>
    </tr>
    <tr>
      <td>{symptom}</td>
      <td>{cause}</td>
      <td>{fix}</td>
    </tr>
  </tbody>
</table>
```

## Cross-references

- Storage macros: `confluence-page/references/macros.md`
- Diagrams: `diagram-plantuml/SKILL.md`