How to read documentation

In a world where an AI agent will happily generate code for you, reading documentation might feel old-fashioned. It's the opposite. Documentation is the ground truth — the authoritative description of how something actually behaves. An agent's answer is a confident guess; the docs are the contract. The skill that compounds is knowing how to check one against the other quickly.

Four kinds of documentation

A common source of frustration is reaching for the wrong type of doc. There are four, and they answer different questions (the Diátaxis framework names them well):

• Tutorial — learning-oriented. Takes you by the hand through a first success. "Build your first app." Great when you're new; useless when you need one specific fact.
• How-to guide — task-oriented. A recipe for a specific goal. "How to upload a file." Assumes you already know the basics.
• Reference — information-oriented. The dry, complete, accurate description of every function, parameter, and option. Where you go to verify.
• Explanation — understanding-oriented. The "why" behind the design. Background, trade-offs, concepts.

When you're stuck, name what you actually need. Learning the lay of the land? Tutorial. Trying to accomplish one thing? How-to. Checking exactly what a function returns when given an empty list? Reference.

How to read a reference entry

Reference docs look intimidating but follow a rigid, learnable structure. For any function, look for:

• Signature — its name, the parameters it takes, and what it returns.
• Parameters — each input: its type, whether it's required, its default.
• Return value — what you get back, and its type.
• Errors / exceptions — what can go wrong and under what conditions.
• Examples — often the fastest way in; read these first.

Read in that order and the wall of text becomes a form you can fill in mentally: "I give it X and Y, I get back Z, and it throws if Y is empty."

Using docs to keep an agent honest

Here's the loop that makes you dangerous (in a good way):

1. Ask the agent to do the thing.
2. Notice the specific function or API it used.
3. Open the reference for that one thing.
4. Confirm the signature, the return value, and the error cases match what the code assumes.

This takes thirty seconds and catches the most common class of agent mistake: plausible code that calls a function that doesn't exist, or passes arguments in the wrong shape. You don't have to read the whole library — just verify the seam where the generated code meets reality.

A quick exercise

Pick any standard-library function you used recently and find its reference entry. Identify each part: signature, parameters, return value, errors. If the docs surprised you about even one edge case, you've just felt exactly why this skill matters.

The knowledge check below is loaded from a sidecar quiz file — proof that quizzes can live alongside lessons as data, not just inline.