A tutorial is a promise: follow these steps and you will end up somewhere better than where you started. Breaking that promise costs a reader an afternoon. This topic collects how we write and maintain tutorials and how-to guides — the structure, the habits, and the review process that keep them usable months later.
What makes a guide worth publishing
Most bad documentation is not badly written, it is badly scoped. Before writing a single step we answer four questions:
- Who is this for? “Everyone” means no one. A guide for someone who has never opened a terminal is a different article from a guide for a developer who already deploys weekly.
- What will they have at the end? A working result they can check themselves, not just a feeling of having read something.
- What do they already need? Accounts, access, tools, and versions — stated up front, because a missing prerequisite is the most common way a tutorial fails.
- What can go wrong? The three or four ways readers realistically get stuck, and what to do about each one.
If those answers are unclear, the guide is not ready to be written. It is ready to be scoped.
The structure we use
Every tutorial of ours follows the same skeleton, because readers should not have to learn a new format on every page:
Prerequisites
A short list before step one: versions, access rights, time needed, and what the reader is expected to know. Anything that is not on this list must not be required later.
Steps that each do one thing
One action per step, one result per step. “Create the file, paste the contents, and restart the service” is three steps, because three things can go wrong. Numbered steps are easier to resume than paragraphs — most readers come back to a tutorial in the middle.
Verification
After the steps, how do you know it worked? A command to run, a page to load, a value to compare. A tutorial without verification is a tutorial the reader has to guess about.
Troubleshooting
The errors that actually showed up while testing the guide, with the cause and the fix. Not a generic “check your logs”, but the two or three specific messages readers will see.
Where to go next
One or two honest next steps. This is also where we link to related guides in the same topic instead of leaving the reader at a dead end.
Write for skimmers and for copiers
People rarely read a guide front to back. They skim headings, copy the block that looks relevant, and move on. So:
- Headings name the action, not the concept: “Set the environment variable”, not “Configuration”.
- Code blocks are complete and copy-pasteable. No
…in the middle, no mixing several shell sessions in one block, no placeholder that silently breaks the command. - Commands and file paths are shown in the same order as the steps that explain them.
- No hidden state. If a step depends on a terminal being in a specific directory, or a service already running, we say so where it matters.
- Screenshots only when the screen is the point — a dialog with five options, a setting in a menu. For code, plain text beats an image every time.
Keep commands, versions, and screenshots honest
Software moves, which means guides rot. Three habits limit the damage:
- Pin versions where the version matters and mention the date the guide was checked, so a reader can judge whether it still applies.
- Test on a clean machine, not on our laptop. A step that only works because of something installed six months ago is not a step.
- Update, archive, or redirect — never leave stale steps standing. If a guide is still useful but outdated, we update it in place and set an “updated” date. If it is obsolete, we archive it or redirect the URL so already-shared links keep working.
Keeping a library of guides from rotting
Individually small habits only work together. We keep a simple register of every guide in a project: who owns it, when it was last verified, and what it depends on. Guides for the same audience live in the same topic, so a reader who solves one problem can find the neighbouring answers without going back to a search engine.
That register is also how we decide what to write next: the questions we answer repeatedly for clients and colleagues, in the order we answer them most often.
What we publish under Tutorial & How-To
Articles in this topic are practical, end-to-end walkthroughs: setting up a project from scratch, connecting a domain, uploading media to object storage, adding redirects, measuring page speed, and recovering when a deployment goes wrong. Each one is tested before it is published — and revisited when the tools behind it change.
Have a problem you keep solving by hand? Tell us about it and it might become the next guide here.