How-to guide vs. tutorial: what's the difference and why does it matter?
Have you ever followed a tutorial, got everything working, and immediately felt lost when you tried to do anything beyond the exact steps you'd followed? Or searched for how to get started with something and landed in a "beginner's guide" that explained every concept in great detail when you just wanted to get something running? When I was a software engineer building REST APIs, that was a constant problem for me: good information was out there, but it didn't have the framing I needed.
The Diátaxis framework addresses this problem by giving technical writers a way to think about what the reader is there to do. Diátaxis divides documentation into four types: tutorials, how-to guides, explanations, and reference.
How-to guides and tutorials are the most commonly confused pair. They look similar on the surface. Both are highly skill-focused. Both involve following steps. But understanding the distinction between writing for someone who wants to learn and writing for someone who wants to get something done will make you a better technical writer.
The tutorial
A tutorial is a learning experience built around a fictional objective. The learner follows real steps and produces a real result, but the result itself is disposable. A sample app they'll never use. A dataset that doesn't represent their actual data. An API key connected to a sandbox environment. The point is never the outcome. The point is what the learner can do afterward that they couldn't do before.
I once took a Hungarian cooking class because I wanted to learn more about my great-grandfather's culture. The instructor had us taste hot and sweet paprika, showed us how to make a roux of paprika, lard, and onion, walked us through some knife skills, and so on. The particular dish we made wasn't really the point. What mattered is that an expert had figured out what could be learned in two hours, curated the experience around that, and sent me home able to keep going on my own.
When you write a tutorial, you are acting as an instructor. You control the environment, the dataset, the outcome. You choose what the learner does, in what order, and why. The reader isn't racing to solve a real problem. What matters is what they understand at the end.
A well-written tutorial is closer to curriculum design than technical writing. You have to engineer a safe learning environment: sample repositories, sandboxed APIs, carefully constructed datasets. The learner needs to follow along without hitting real-world complications that would derail the lesson. This is significant additional work, and it's why tutorials are often the most difficult documentation to write well.
The how-to guide
A how-to guide is a task-oriented document. The reader has a genuine objective: they want to get your API running in their application, set up their development environment, or send their first request. They need a reliable path to the finish line.
Back to the cooking analogy: a how-to guide is like my mom's recipe book. She knows I already know how to cook. She knows I'm reading the book because I'm in the kitchen and the stove is on. I just need to know what ingredients to buy and in what order to combine them. There might be specialized guidance ("only use this brand!"), but she doesn't need to tell me what to do if the sauce breaks or how to tell when the meat is properly rested. I already know, or I can figure it out. That's not a flaw, it's a feature. Including it would just get in the way.
A good how-to guide respects what the reader already knows. It assumes competence, skips what doesn't need to be said, and cuts anything that stands between the reader and their goal.
At a glance
| Tutorial | How-to guide |
|---|---|
| The goal is to learn. | The goal is to accomplish something. |
| The reader is a beginner acquiring new capability. | The reader already has some competence and needs to apply it. |
| The result is disposable — a sample app, a sandbox environment, a dataset that doesn't matter. | The result is real — something the reader actually needs. |
| The writer controls the environment. Everything is prepared in advance. | The environment is the real world. Anything can go wrong. |
| Explanations are essential. The reader needs to understand why. | Explanations get in the way. The reader needs to know what to do. |
| Follows a single, carefully managed path. No forks, no alternatives. | May branch depending on the reader's situation. If this, then that. |
| Responsibility lies with the writer. If the reader gets stuck, the tutorial has failed. | Responsibility lies with the reader. The how-to guide points the way; the reader navigates. |
| Assumes nothing. Explains where to click, what to type, how long to wait. | Assumes competence. Skips what the reader already knows. |
Why the distinction matters in practice
The confusion between these two document types usually produces a hybrid that does neither job well. A tutorial that's really just a how-to guide fails the learner: it gets them to a working state without building genuine understanding, and they'll be lost the moment something goes wrong. A how-to guide that's really a tutorial wastes the experienced developer's time with explanations they don't need and steps they didn't ask for.
When you're planning documentation, ask yourself: is my reader here to learn or here to do? If they're here to learn, write a tutorial. If they're here to do, write a how-to guide. That question should shape every decision you make about the document: what you include, what you leave out, how much you explain, and how much you assume.
Most documentation problems that get blamed on poor writing are actually problems of misidentified document type. A writer sat down without first asking what kind of document their reader actually needed. That's a fixable problem, and now you know how to fix it.
If the ideas in this post resonated with you, I'm launching a course that teaches exactly this — the technical skills and professional instincts that working technical writers actually use. Check it out here — founding member pricing is available to early subscribers.
