How-to Guides — From Goal to Proof
On your first day, Nightjar's quick start failed you twice: it never mentioned logging in, and it never mentioned verifying the alert email, the step behind most of the 46 "no alert" tickets a month. Everything in this course meets in the fix. A how-to guide takes one reader from one goal to a result they can see with their own eyes.
The rule
One goal, prerequisites first, one action per step, then prove it worked.
A how-to guide has a dependable skeleton:
- Title: a verb and the goal, such as "Add your first monitor".
- Opening line: what the reader will achieve, in one or two sentences.
- Before you start: everything needed before step 1, such as an account, a plan or an installed tool.
- Steps: numbered, one action each, in the imperative ("Run", "Select"), with exact commands and interface labels, and the expected result after any step where readers could go wrong.
- Check it worked: how the reader can see success.
- Next step: one call to action.
What stays out: long explanations (link the concept page instead) and every alternative path (give those their own guides).
# Add your first monitor
Get an email within minutes whenever your site stops responding.
## Before you start
- A Nightjar account (the Free plan is enough)
- The Nightjar command-line tool, installed
## Steps
1. Run `nightjar login`. Your browser opens; select **Approve**.
2. Run `nightjar monitors add https://shop.example.com --interval 5m`.
The tool prints `Monitor created` and the monitor's ID.
3. Open the email Nightjar sent when you signed up and select **Verify alert email**.
4. Run `nightjar alerts test`.
## Check it worked
Within a minute, a test alert arrives in your inbox.
Next: [add an SMS alert channel](sms-alerts.md) so outages reach your phone.The shortcut
Build every guide as goal, given, do, done: state the goal, list what is given before you start, write what to do one action at a time, and prove it is done.
Goal
"Add your first monitor and receive a test alert." One goal. SMS setup moves to its own guide.
The trap is the guide that bundles several actions into one step, never shows what success looks like, or stops before the reader can confirm it worked.
Drills
Answer fast — trust the rule.
Where do the prerequisites go in a how-to guide?
Which step is written well?
Why show the expected result after a step, such as "The tool prints Monitor created"?
One guide covers setting up email, SMS and Slack alerts, with "if you chose SMS" branches everywhere. What is better?
Which is the best "Check it worked" section for the first-monitor guide?
Remember
- One goal, prerequisites first, one action per step, then prove it worked.
- Shortcut: goal, given, do, done, then test it on a clean machine.
- Trap: bundled steps, no visible results, and endings before the proof.