How to Prevent 'It Works on My Machine' Frustration in Tutorials
I was following a deployment tutorial last week. Same Node version, same OS, copied the commands exactly. Around step 4, I got an error the guide never mentioned. I went back and checked everything, ran the command again. Same error. The tutorial just kept going like nothing could possibly go wrong.
Turns out nothing was actually broken on my end. The writer hit that same error when they were testing, fixed it, and then just didn't mention it in the final version.
I used to do this too. Test the tutorial, hit errors, fix them quietly, then write it up like everything went smooth. But over time I've realized that list of errors I hit? That's actually the most valuable part for readers. When I skip it, I'm making their experience harder for no reason.
Which docs need a troubleshooting section?
A reference doc listing API parameters doesn't need a troubleshooting section. A guide explaining how OAuth works doesn't either.
But if you're writing a tutorial, how-to guide, or quickstart where people follow steps to build something, you need one. Your readers need help when things don't work.
When you write step-by-step instructions, you're basically creating a list of things that can break. Every command is a place where someone's setup might be different from yours. And if you already tested it, you know exactly where those breaking points are because you ran into them yourself.
What happens when you hide the errors you hit
Watch any popular dev tutorial on YouTube. The presenter breezes through an install with no errors and clean terminal output every single time. What you don't see is the three takes it took to get there, or the fact that they're on a fresh Docker container with nothing else installed.
Written tutorials do the same thing. Writers run the steps, hit errors, fix them quietly, then write the "clean" version as if nothing went sideways. The result looks polished, but it creates a false picture of reality for anyone whose environment is even slightly different.
"The errors you hit while building the thing are the exact errors your readers will hit while following you."
You already solved all these problems when you were testing. Just write down what you did.
A real example: Installing bcrypt
Say you're writing a guide on adding password hashing to a Node.js app using bcrypt. The install step in your tutorial looks like this:
npm install bcrypt
Output:
Looks fine. But on a machine without Python or the right build tools installed, here's what actually shows up:
npm warn install Usage of deprecated folder mapping "./" in the "exports" field module resolution
npm error gyp ERR! find Python
npm error gyp ERR! find Python Python is not set from command line or npm configuration
npm error gyp ERR! not ok
A reader who hits this and doesn't see it addressed in the tutorial will spend the next hour on Stack Overflow, or just assume they broke something and start over. The fix is short:
bcryptneeds Python and build tools to compile. On Windows, install them withnpm install --globalwindows-build-tools. On macOS, runxcode-select --installto get the Xcode Command Line Tools. Or just usebcryptjsinstead - it's pure JavaScript so no build tools needed, and the API is identical.
That's a short paragraph, and it saves a chunk of your readers from a frustrating detour. Write it while the error is still fresh in your terminal.
What a good troubleshooting section looks like
You don't need a wall of text. The simplest format is a table: error on one side, cause and fix on the other. Readers scan it fast, match what they're seeing, and move on.
| Error | Likely cause | Fix |
gyp ERR! find Python | Python not installed or not in PATH | Install Python 3.x and make sure it's in your PATH. On Windows, also run npm install --global windows-build-tools |
Error: Cannot find module 'bcrypt' | Package installed globally or install failed silently | Run npm install bcrypt from inside your project directory, not globally |
EACCES: permission denied | npm trying to write to a directory it doesn't own | Don't use sudo. Fix npm permissions using the official npm guide on fixing permissions instead. |
Where to put it
For short guides with 5-8 steps, add the troubleshooting section at the end. People who get stuck will scroll down to find help anyway.
For longer tutorials, add troubleshooting after each major section (setup, configuration, deployment). Nobody wants to scroll through the entire guide to fix an error from step 3.
For quickstarts, keep it tight. One callout block covering the two or three most common errors is enough. The goal is a fast path to working, not exhaustive coverage.
In Summary
Step-by-step content (tutorials, how-to guides, quickstarts) needs a troubleshooting section.
The errors you hit while writing the guide are the same ones your readers will hit.
A simple error/cause/fix table is all you need.
Put it at the end of short guides, or at the end of each phase in longer ones.
Screenshot the actual error output. Readers need to recognize it.
When you hit errors while writing tutorials, write them down. You're going to fix them anyway, so why not tell readers what worked?
