Reading Documentation

Goal, relevant concept, minimal section, try the example, modify it, apply. Documentation before tutorials, tutorial dependency, and search as a skill.

Reading Documentation With a Goal

Documentation is consulted, not read. Start from the goal, find the concept that owns it, read the smallest section that answers it, run the example, change the example until it breaks, then apply it to your problem — and stop reading the moment the next step is obvious.

Q · The library you need has three hundred pages of documentation and you need one thing from it. How do you read enough — and only enough — to get that thing working in your own code?
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.

Q · 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?
A Reading Strategy for an Unfamiliar Library

Given a library's documentation and no prior knowledge, find five things and stop: how to install it, the one abstraction everything else is built on, one API call you can run, what it does when something goes wrong, and one limitation that would matter in production.

Q · You have been pointed at an unfamiliar library's documentation and told to evaluate it by tomorrow. What are the five things you must find before you have read enough, and how do you find each one?
Tutorial Dependency

If you can only build what a tutorial builds, you have not learned the tool; you have learned the tutorial. The way out is a ladder: follow it, modify it, build something similar without it, then build from requirements alone — and the last rung is where the understanding is tested.

Q · You have followed a dozen tutorials and can reproduce each one, but a blank requirement leaves you stuck. How do you tell tutorial fluency from understanding, and how do you get from one to the other?
Search as a Skill

"My code no work react" finds nothing; "React stale closure useEffect interval" finds the answer in the first result. The query is a compressed statement of what you understand about the problem, and evaluating what comes back — authoritative, current, your version, explains why — is the second half of the skill.

Q · Something is broken and you are about to search for it. What makes one query find the answer and another find nothing, and how do you decide which of the results to believe?