❯ How to write a how-to that people actually finish

2026-09-24 ·5 min read

by Priya Anand — the product desk, Side Quest Studios September 25, 2026

Most how-tos don't fail because they're wrong. They fail because nobody finishes them.

I've written runbooks that saved a fleet at 3am and I've written docs that collected dust for two years. The difference was never the quality of the prose. It was whether I respected the reader's time and their failure modes. That's the whole game.

Here's what I've learned after too many years of watching people abandon step 4 of 12.

Start with the outcome, not the origin story

Nobody reads a how-to to learn about you. They read it because something is broken, missing, or slow, and they want it fixed before lunch.

So the first line of any how-to I write is the finish line. Not "Introduction." Not "Background." The thing they'll have when they're done.

Bad: "Kubernetes is a container orchestration platform that..."

Good: "By the end of this, you'll have a working Postgres replica on a second box that stays in sync and survives a reboot."

That one sentence tells the reader whether to keep reading. If they don't need a replica, they close the tab and you've done them a favor. If they do, they're now invested because you named the exact thing they want.

I learned this the hard way. Years ago I wrote a 40-step guide to setting up a mail server. It started with a paragraph about the history of SMTP. Every single person who tried to follow it got lost somewhere around step 9. When I rewrote it starting with "You'll have a mail server that sends and receives for one domain, with TLS, in about 40 minutes," completion went from "basically zero" to "people actually emailing me questions about step 22." That's progress.

One idea per step, one action per step

The killer of how-tos is compound steps. "Install the package, configure the config file, and restart the service." That's three steps wearing a trench coat. If the restart fails, the reader doesn't know which of the three broke.

Split it. Every step does exactly one thing and produces exactly one observable result.

bash bash (80x24)

# Step 3: Install Postgres
$ sudo apt install -y postgresql-16

# Step 4: Verify it's running
$ systemctl status postgresql

Two steps. Two things the reader can confirm. If step 4 shows inactive (dead), they know exactly where they are and can stop and ask for help instead of pushing forward into a wall.

This is the single biggest difference between a how-to that works and one that doesn't. Compound steps are how you lose people. They think they did it wrong. They aren't sure which part failed. They give up.

Show the output

Every command should be followed by what the reader should actually see. Not a description of what they'll see. The actual text.

terminal bash (80x24)

$ systemctl status postgresql
● postgresql.service - PostgreSQL RDBMS
     Loaded: loaded (/lib/systemd/system/postgresql.service; enabled)
     Active: active (exited) since Thu 2026-09-18 09:14:22 UTC

Now the reader can compare. Green text? Match? Move on. Red text? Mismatch? Stop and read the troubleshooting section.

The reason this matters: your reader is tired. They're doing this at 11pm because something broke in production and they want to go to bed. They don't want to interpret. They want to compare. Give them the exact string to compare against.

Anticipate the three ways it will break

Every real how-to has three or four failure modes that account for 90% of the "it didn't work" messages you'll get. Write them down. Not as an afterthought. As a section.

I don't mean "if something goes wrong, check your configuration." I mean:

If systemctl status shows failed:

Check /var/log/postgresql/postgresql-16-main.log. The most common cause is that port 5432 is already in use. Run ss -tlnp | grep 5432 to see what's holding it.

That's specific. It names a file. It names a command. It names a symptom. And it saves you twenty emails.

The trick is to write the troubleshooting section while you're doing the thing, not after. When you hit a snag during your own walkthrough, that snag is the section. Write it down while you're annoyed. That's your best prose.

Don't make them install anything they don't need

Every dependency you add is a step where someone bails. Every "just install Docker first" is a fork in the road where half your readers go home.

If curl and jq will do it, don't reach for a framework. If systemd timers will run your job every 15 minutes, don't install a scheduler. If ssh and rsync will move the files, don't stand up an object store.

This isn't dogma. It's arithmetic. The reader who has to install a new tool is the reader who closes the tab and never comes back. The reader who runs one command they already have is the reader who finishes.

I had a how-to that required a Python library. Completion was fine. I rewrote it to use python3 -m http.server and curl, no installs. Same outcome. Completion went up because the friction went to zero. If you can do it in bash and coreutils, do it in bash and coreutils.

Test it on a clean box

This is the part everyone skips. You wrote the how-to on your laptop, where you have 47 things installed and your shell history is a mile long. Of course it works. Now run it on a fresh VM.

bash bash (80x24)

multipass launch --name test --cpus 2 --memory 2G --disk 10G
multipass shell test

Then follow your own instructions. Word for word. Don't cheat. Don't skip. Don't fix things on the fly because "obviously they'd know to do that."

Every time you have to fix something on the fly, that's a bug in your how-to. Write it in. Every time a command fails because you assumed something was installed, add the install step. Every time the output looks different than you remembered, update the expected output block.

This is the whole trick. The how-to that was tested on a clean box is the how-to people finish. The one that wasn't is the one you'll be answering questions about for a year.

Give them a way to verify they're done

Last step of every how-to I write is a verification. Not "you should be done now." An actual command that returns an actual result that means success.

bash bash (80x24)

# Final check: connect from another host
$ psql -h 10.0.0.42 -U app -d appdb -c "SELECT 1;"

If that returns 1, you're done. If it doesn't, go back to the troubleshooting section.

People need to know when to stop. Without a finish line, they'll keep second-guessing. They'll re-run steps. They'll break things. Give them the green light.

The meta-lesson

A how-to is not a document. It's a promise that the reader's problem will be solved if they follow along. Every sentence you write either reinforces that promise or breaks it.

That's why I don't write introductions. Why I don't tell stories about why I built the thing. Why I don't link to "further reading" in step 3. The reader has one job: finish. My job is to remove every obstacle between them and done.

Which is the same job as keeping a fleet alive at 3am. You don't get points for elegance. You get points for the service coming back up.

Write the how-to like the reader is tired, distracted, and one bad step away from giving up. Because they are. And if you write for that person, everyone else finishes too.

Same thing applies to the systems behind the docs — we build and run these at hub.sqs.chat if you'd rather not rebuild the plumbing yourself.

References

AI-assisted, curated for Side Quest Studios.