Documentation Before Tutorials
A tutorial shows one path through a tool, chosen to be watchable. Primary documentation states the contract. Read the contract for anything your system will depend on, and use tutorials for what they are good at: orientation, vocabulary, and seeing the pieces connect once.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
When you meet a technology for the first time, what should you read first — the primary documentation or a tutorial — and what does each one actually give you?
You need to add file upload for product images. There is a forty-minute video that builds an image uploader with exactly the library you chose, and there is the library's documentation, which is dry and has no pictures. The video is obviously the faster path to a working uploader, and you have a working uploader by lunch.
Follow the tutorial. It is sequenced, it has a running result at the end, and it removes every decision — which storage, which validation, which error handling — so that nothing blocks the path to something that works on screen.
The uploader works and nobody on the team can say why. The tutorial made the decisions — where the file goes, what happens on a large file, whether the upload is validated before or after storage — and those decisions are now in the store without anyone having made them.
- The uploader works and nobody on the team can say why. The tutorial made the decisions — where the file goes, what happens on a large file, whether the upload is validated before or after storage — and those decisions are now in the store without anyone having made them.
- The first requirement the tutorial did not cover stalls everything. The tutorial uploaded from a form; the store needs to upload from the admin page and then attach the image to a product. The tutorial had no concept of "attach", and neither does the reader.
- Errors that the tutorial skipped arrive in production. The video cut away when the upload failed, or never tried; the store's first customer with a slow connection finds the path the video did not walk.
- The tutorial was written for a version that is not the one installed, and the difference surfaces as a mysterious failure that neither the tutorial nor the reader's understanding can explain.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Separate what each source is for. A tutorial is a single walked path: it gives orientation, vocabulary and the experience of the pieces connecting once. Primary documentation is the contract: what the tool promises, what it requires, what it does when things go wrong. Neither replaces the other; the mistake is using one for the other's job.
- For anything your system will depend on — the upload library's validation, the storage client's failure behaviour — read the contract. For a first look at an unfamiliar area — "what does an upload pipeline even consist of?" — a tutorial is a fine map, as long as you know you are holding a map and not the territory.
- Use the tutorial to find the concepts, then go to the documentation for each concept the tutorial used and read what it actually promises. The tutorial tells you which pages to read; the pages tell you what is true.
- Treat every decision the tutorial made silently as a decision you now have to make explicitly. List them. Each one is either confirmed against the docs and your requirements, or changed.
What each source is actually for
The disagreement about tutorials dissolves once the question changes from "which is better" to "which gives what". A tutorial gives a path and the experience of walking it. Documentation gives the contract and the space of paths. Asking a tutorial for the contract is what produces inherited decisions; asking the documentation for orientation is what produces a day in the reference with nothing running.
The pair below makes the failure concrete. The worse column is not stupid — it is the natural reading of a tutorial. The better column is the same tutorial, read as a map.
Follow the upload tutorial to the end, paste the result into the admin page, and ship it. Storage is local disk, there is no size limit, validation happens after the write, and failure shows a blank page — none of which anyone chose.
Follow it to learn that an upload pipeline has a receiving endpoint, a type check, a size limit, a storage target and a reference back to the product. Then read the documentation entry for each of those and decide each one against the store: object storage, a limit, pre-storage validation, an error shown to the admin.
The tutorial's decisions were made for the video's constraints — short, watchable, works on the presenter's laptop — and the store has different constraints. Only the documentation states what the options are, so only the documentation lets you choose.
Which to open first
The choice is not fixed; it depends on what you already have. With no vocabulary, a tutorial first. With vocabulary and a specific goal, documentation first. With a tool the system will depend on in production, documentation is required whichever came first in time.
The decision below is a set of criteria, not a rule. The cost column is what you pay for choosing that path, and it is never nothing.
What do I need from my first contact with this tool?
when You have no mental model of the area — you could not name the parts of an upload pipeline — and need to see the pieces connect once.
cost You inherit its decisions and must list and re-make each one; you are learning one path through a space whose shape you still cannot see.
when You know the vocabulary and have a goal in one sentence; you need the contract for a specific call, or the tool will carry production traffic.
cost Slower to first running result; the composition of the pieces is left to you, and the general case is described where you wanted the specific one.
when Almost always, when the tool will stay in the system: the tutorial gives the reading list, the docs give the truth.
cost Roughly double the time of either alone, spent on the tutorial's calls whether or not they were the right ones for your problem.
when The documentation is thin or wrong for your version, and the behaviour you depend on is in the code or the tests.
cost Slowest, and it teaches the implementation rather than the intent; what you learn may change in the next release (Reading a Codebase).
How inherited decisions surface
Each silent decision in a tutorial has a moment when it stops being silent. The table is not exhaustive; it is the image-upload tutorial's four decisions, followed to the point where each one would have been noticed, and what the documentation would have said had it been read.
The response column is the same in every row: find the contract, make the decision, and write down that it was made. That is the whole lesson in one column.
| Trigger | Symptom | Cause | Response |
|---|---|---|---|
| The store is redeployed | Every product image disappears | The tutorial stored files on local disk, which the new container does not have. | The storage client's docs list the targets; object storage was one option away. Decide, and note why. |
| An admin uploads a raw camera file | The upload hangs, then the disk fills | No size limit; the option defaulted to unlimited and the video never mentioned it. | The reference entry names the option and its default. Set it against the requirement, not the default. |
| A file with an image extension and non-image content is uploaded | A broken image on the product page | Validation by extension after storage, because that ordering made the video shorter. | The docs offer a pre-storage content check that rejects with a reason. Move validation before the write. |
| The storage service is briefly unavailable | The admin sees a blank page and retries, producing a duplicate | The tutorial cut away before any failure; there is no error path and no idempotency. | The client's error types are documented; show the admin the reason and make the retry safe (Duplicate Requests). |
How to do it
Most important first.
- Before following a tutorial, write what you want to learn from it: "the shape of an upload pipeline and the names of its parts", not "a working uploader". The first is what tutorials are good at.
- While following it, keep a list of decisions it makes without discussing them — storage location, size limit, validation order, error handling. The list is usually longer than the tutorial.
- After it runs, open the primary documentation for each library call the tutorial used and read the entry: arguments, defaults, errors. Compare with what the tutorial did (Reading Documentation With a Goal).
- Check the version. A tutorial pinned to an older major version is a map of a different territory; the changelog between the two is required reading before trusting it.
- Rebuild the tutorial's result from the documentation alone, without the video open. Where you cannot, you have found what the tutorial was doing for you (Tutorial Dependency).
- Decide each silent decision explicitly against the store's requirements, and write the ones that differ into the unknowns board or the decision journal (The Decision Journal).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The image-upload tutorial: it stores files on the local disk, sets no size limit, validates the file type by extension after storing it, and shows no failure path. Four silent decisions. Against the store's requirements: images must survive a redeploy (so not local disk), a limit is needed (an admin could upload anything), type validation must happen before storage (or the disk fills with junk), and a failed upload must tell the admin what happened.
- The documentation for the upload library says the type check can be a pre-storage filter, that the size limit is an option defaulting to unlimited, and that a rejected file raises a specific error with the reason. None of that was in the video; all of it was in the reference entry the video was silently using. Twenty minutes of documentation after the tutorial turned four inherited decisions into four made ones.
- Where a tutorial was the right first read: nobody on the team had seen a realtime chat pipeline. A tutorial that built one — connection, room, message, broadcast, read state — gave the vocabulary in an hour that the transport documentation would have given in a day. Then each concept was read up in the docs, and the tutorial's choice of transport was re-examined against the chat app's requirements (Choosing a Real-Time Transport).
How you know it worked
What now exists that did not before, and what question you can now ask.
- You can list the decisions the tutorial made for you, and say for each one whether you kept it and why.
- You have read the documentation entry for every call the tutorial used, and at least one of them said something the tutorial did not.
- You can rebuild the tutorial's result from the docs without the tutorial open.
- The tutorial's version and your installed version are known to match, or the differences are known.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?Am I reading this to find out what the tool promises, or to see the pieces connect once?
- ?Which decisions did this tutorial make without discussing them, and which of those does my system depend on?
- ?For each library call the tutorial used, what does the documentation say it does on failure?
- ?Does the tutorial's version match the one I installed, and if not, what changed between them?
- ?Could I rebuild this from the documentation alone — and where I cannot, what was the tutorial doing for me?
What can go wrong
- Documentation purism: refusing tutorials entirely, and spending a day in reference pages for a concept a tutorial would have shown in an hour. Tutorials are the fastest way to see pieces connect; the failure is stopping there, not starting there.
- The decision list is written and never acted on. Naming a silent decision is not making it; each one still has to be checked against the docs and the requirements.
- Reading the documentation for everything the tutorial touched, including the parts your system will never depend on. Read the contract for what you depend on; skim the rest.
- Trusting a tutorial that is current and well made as if it were the docs, because it happens to be right. It may be right; you still cannot tell without the contract, and the next tutorial will not be.
- Reading the contract after the tutorial roughly doubles the time to the first working version. On a throwaway prototype, that time may be worth more elsewhere.
- Documentation states the general case and leaves the composition to you; the tutorial's value was precisely that it composed the pieces, and reading the docs does not replace that experience.
- Listing silent decisions surfaces choices the team must now make, which is slower than inheriting them — and correct only when the choices matter.
- "Tutorials are for beginners." Tutorials are for orientation, and seniors need orientation in unfamiliar areas as much as anyone. The difference is that a senior knows what the tutorial is not giving them.
- "If the tutorial's result works, its decisions were fine." The result working proves the happy path on the tutorial's inputs. Whether local-disk storage was fine depends on your deployment, which the tutorial never saw.
- "Documentation before tutorials means never watch the video first." Watch it first when you need vocabulary; read the docs first when you already have it and need the contract. The rule is about which source carries which weight, not about clock order.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALThe division of labour — tutorials for orientation and composition, documentation for the contract — holds for any tool; where a tool has no good documentation the contract has to be recovered from its source or its tests, which is slower but the same job.
- CONTESTEDThe tutorial-first camp holds, with reason, that a beginner cannot read a reference until they have a mental model to hang it on, that a well-made tutorial builds that model faster than any documentation, and that reading the contract for everything before touching anything is a recipe for never starting. Their strongest point is that comprehension needs a working example to attach to. This lesson agrees for orientation and disagrees for dependence: the tutorial can go first in time, but the contract must be read before the tool is relied on.
- ILLUSTRATIVEThe forty-minute video, the four silent decisions and the twenty minutes of reference reading are invented to show the shape of the argument; no real tutorial is being reviewed.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto at /manifesto/delegating: a tutorial delegates the decisions as well as the typing; the cards there are a good template for listing what it decided for you.