Anatomy of a good guide: how we write everything here

Every article on this site — the blog and the guides alike — is written to the same handful of rules. This post is both the explanation and the demonstration: everything described below is used on this page.

If you write for us, or you are curious how the sausage is made, this is it.

Rule one: answer the question in the first paragraph

Nobody arrives at a support article for the pleasure of reading. They have a broken thing and a diminishing amount of patience.

So the answer comes first, and the background comes after it. The reader who already knows the context gets what they came for in ten seconds; the reader who needs the background scrolls.

The most common failure in technical writing is not being wrong. It is being right in the eleventh paragraph.

Rule two: show the actual thing

Instructions that describe a screen are worse than the screen. Where a picture genuinely helps, we use one — and where several do, they go in a gallery so the page does not turn into a scroll marathon.

Click any of them to see it full size. Arrow keys move between images, Escape closes.

A single image gets a caption of its own rather than a gallery:

Rule three: code you can copy, not code you must retype

Anything the reader has to enter is a code block, complete, with no placeholder they have to decode.

Type  Host  Value                                     TTL
TXT   @     "v=spf1 include:_spf.myeasybase.ca ~all"  3600

Commands get the same treatment, one per line, in the order they are run:

nslookup -type=ns yourbusiness.ca
dig +short yourbusiness.ca
curl -sI https://yourbusiness.ca | head -n 1

And where a config file is involved, it is shown as a file, not paraphrased:

'mail' => [
    'host' => env('MAIL_HOST', 'mail.yourbusiness.ca'),
    'port' => (int) env('MAIL_PORT', 465),
    'encryption' => 'tls',
],

Inline values — a filename like wp-config.php, a port such as 993, a flag like --recursive — get inline code formatting so they are unmistakably literal.

Rule four: tables for anything with more than two dimensions

Prose is bad at comparison. A table is not.

Wide tables scroll inside themselves rather than pushing the page sideways, which matters because roughly two thirds of the people reading this are on a phone.

Rule five: warn people before they break something

Three kinds of aside, used sparingly. If everything is highlighted, nothing is.

Rule six: numbered steps only when order matters

If the reader must do things in sequence, number them:

1. Take a backup and download it somewhere that is not the same server.
2. Lower the DNS TTL to 300 and wait a day for the old value to expire.
3. Copy the files and the database across, then test on a temporary address.
4. Change the records. Most visitors move within five minutes.
5. Issue the SSL certificate — this only works after the domain resolves here.

If order does not matter, use bullets instead, and keep them parallel:

• Resize images before uploading. A phone photo is several megabytes.
• Turn on two-factor authentication. Ninety seconds, enormous payoff.
• Check the billing email is one you read. Not one at the domain that is expiring.

Rule seven: write for the person having the bad day

Plain words. Short sentences. No "simply", no "just", no "obviously" — every one of those tells a stuck reader that their problem should not exist.

Say we when it is our fault. Say what it costs when there is a cost. And if the honest answer is that the reader should not buy the thing we are selling, say that too. We have a whole article arguing some businesses only need a Google listing.

The rules, briefly

That last one is the only test that really matters. The rest are how you pass it.