Marcos Silva
73 lines
1.8 KiB
Markdown
73 lines
1.8 KiB
Markdown
# 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`
|