Tutorial

Origin & evolution

The sharpest articulation of what a tutorial is comes from Daniele Procida's Diátaxis framework, which sorts technical documentation into four kinds answering four distinct needs🫀NeedUserA user need, pain, desire, or constraintView reference →: tutorials, how-to guides, reference, and explanation. Diátaxis defines a tutorial as a lesson that takes a student by the hand, always practical, always under the guidance of an instructor. Its purpose is learning, so its measure of success is that the beginner finishes feeling capable, even if the route taken was not the one an expert would choose.

That precision matters because the four types fail when mixed. Simon Willison's widely-read summary of the framework notes how teams that conflate a tutorial with a how-to guide produce documentation that serves neither: the beginner gets lost in options, the expert gets slowed by hand-holding. Diátaxis named a distinction practitioners had felt for years without language for it, which is why the model spread quickly through documentation teams after Procida formalised it.

The framework's discipline is subtractive. A tutorial earns its keep by leaving things out: no edge cases, no alternative paths, no explanation of why the system works the way it does. Those belong to reference and explanation. The tutorial's one job🔨JobUserJob To Be Done: what the user is trying to accomplishView reference → is to get a beginner to a working result, building the confidence that makes the rest of the documentation usable.

How it works in practice

A design tool publishes a tutorial called "Build your first interactive prototype📱PrototypeExperience DesignAn interactive mockup for testingView reference →." It opens with a promise of the end state, a clickable three-screen flow, and walks the reader through exactly that, with no detours. Steps are numbered, every click is named, and the screenshots match the current build. There is no mention of the seventeen other transition types, because a beginner choosing among seventeen options learns nothing.

The metric🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference → the team watches is completion-to-activation: of users who finish the tutorial, what fraction go on to build a second prototype unaided within a week. When that number sits at sixty-one per cent and the abandonment cluster is at step four, the team knows the lesson is mostly working and exactly where it snags. They fix step four. They resist the urge to add content, because every addition lengthens the path to the first success.

Tutorial vs. its neighbours

• A walkthrough🚶WalkthroughCustomer EducationA guided product walkthroughView reference → runs inside the live product as a guided tour, with tooltips and coachmarks layered over the real interface. A tutorial is a standalone document the learner follows at their own pace. The walkthrough drives you through the actual screens; the tutorial teaches outside them.
• A knowledge base article📓Knowledge Base ArticleContent & KnowledgeA knowledge base articleView reference → is reference or troubleshooting: it answers a specific question for someone who already knows what they are doing. A tutorial teaches a beginner from zero. One serves recall, the other serves first learning.
• A learning path🥾Learning PathCustomer EducationA structured learning pathView reference → is a sequence of tutorials and other units arranged toward a competency. The tutorial is a single rung; the path is the ladder. A path gives tutorials an order and a destination.

In the graph

In the Unified Product Graph, a tutorial sits within the education region as a teaching unit owned by a program and arranged inside a path. It connects upward through education_program_teaches_via_tutorialEducation Programteaches viaTutorialhierarchy and learning_path_contains_tutorialLearning PathcontainsTutorialhierarchy, and outward to the product it teaches through tutorial_explains_featureTutorialexplainsFeaturecross-domain and tutorial_references_knowledge_base_articleTutorialreferencesKnowledge Base Articlecross-domain. Those edges encode the Diátaxis boundary structurally: a tutorial points at the feature⭐FeatureProduct SpecificationA product capability or featureView reference → it teaches and links out to the reference material rather than absorbing it, so the lesson stays a lesson and the encyclopedia stays separate.