ai-for-dummies/public/submitted-skills/Marcos Silva/templates/how-to.md

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

<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