| name | writing-tutorials |
| description | Write a Diátaxis tutorial, ie learning-oriented documentation that teaches a beginner a skill through a guided, hands-on lesson. Use when the goal is to take someone new and give them a successful first experience, not to solve a specific problem (that is a how-to guide) or to explain concepts (that is explanation). Load the `diataxis` skill first if unsure which mode applies. |
Writing tutorials
A tutorial is a lesson. It is an experience, guided by you the tutor, that is always learning-oriented. Success is not measured by the artifact produced or whether the learner can later repeat it alone. It is measured by what the learner acquires and whether they finish feeling capable and willing to return.
The tutor carries nearly all the responsibility. The learner just follows.
The contract
The learner agrees to follow your instructions exactly. In return every instruction must work, every time, for every learner. A single step that fails to produce the promised result shatters confidence and breaks the lesson. Aim for a tutorial so well constructed that things cannot go wrong. Test it by watching real users.
How to write one
- State the destination up front. "In this tutorial we will build and deploy a small web app." The learner needs to know where they are going and to feel progress toward it.
- Deliver a visible result at every step. Each action produces an outcome the learner can see and understand right away. Fast feedback ties cause to effect and removes anxiety.
- Narrate expectations. "You will notice that..."; "The output should look something like...". Prepare them for what is coming and flag the signs of trouble.
- Point out what to observe. Learners absorbed in the task miss cues. Tell them to notice the changed prompt, the new file, the unexpected line of output.
- Keep it concrete, never abstract. Lead them through specific, tangible actions. Patterns and generalizations form on their own from concrete experience.
- Allow repetition. Avoid irreversible steps so a learner can run it again. Repetition builds confidence and is sometimes the only teacher.
Language patterns
- "We..." affirms the togetherness of tutor and learner.
- "First, do x. Now, do y." plain imperatives remove all ambiguity.
- "Notice that... Remember that..." confirmation and reinforcement.
- "You have built..." acknowledges the accomplishment.
What to avoid
- Explaining. The single biggest mistake. The learner wants to do, not understand abstractions yet. Keep justification to a brief clause ("we use HTTPS because it is more secure") and link out to an explanation for the rest.
- Offering choices, options, or alternatives. Every fork is cognitive load and a chance to go wrong. Pick one path and stay on it. Options belong in reference.
- Aiming for completeness of the subject. A tutorial teaches a slice well, not everything. An incomplete lesson the learner enjoyed is a success.
- Unreliable steps. See the contract above.
The test
Think of teaching a child to cook. The dish is the pretext. What they actually acquire is knife handling, timing, washing up, vocabulary, all through doing. If they achieved something and want to come back, you succeeded.
