Comparisons
Pairs engineers genuinely confuse — goal and implementation, MVP and bad prototype, prototype and spike, reversible and irreversible. Neither column wins; what decides is the problem. Each record leads with the confusion, because the confusion is what it costs.
Documentation vs tutorial
The tutorial is mistaken for a picture of production. Its cart is client-side because that made the video shorter; its checkout skips payment failure because that made the video watchable; its folder structure is one person's habit. Building the product on the tutorial's decisions means inheriting choices nobody made for this problem. The other cost is dependency: a learner who can build only what a tutorial walked through cannot start anything. The strongest form of the tutorial side is that a working example is the fastest way to orient and to learn the vocabulary the documentation assumes; the honest reply is to use it for that, and then read the documentation for the concept you need and modify the example until it is yours.
When you know the concept you need and want to use it correctly, and whenever you need to know what a thing guarantees rather than what it does in a demo.
On the first day with a new tool, to see the shape of a working example and the vocabulary. Then close it.
| Aspect | Documentation — a reference to what each part is, what it guarantees and how to use it | Tutorial — a walkthrough that builds one example the way its author chose to |
|---|---|---|
| Answers | "What does this do and guarantee?" | "How did one person build one example?" |
| Structure | By concept | By the author's sequence |
| Design decisions | Yours to make | Already made, for the video |
| Reading strategy | Goal, concept, minimal section, try, modify, apply | Follow once, then close it |
| Failure cases | In the reference, if you look | Usually cut for length |
| Typical mistake | Reading it cover to cover | Building the product on its architecture |