S004 · Reading Docs & Effective Googling — the Meta-Skill

Module M00: Setup & Tools · Session 4 of 130 · Track: Setup 🔍

What you'll be able to do after this session

• Explain Reading Docs & Effective Googling to a friend in one minute, out loud, no notes.
• Recognise it when you see it in real code / systems / papers.
• Complete the hands-on exercise at the end without looking up help.

Prerequisites

If you can't answer these in 30 seconds each, redo the linked session first:

• S001 — Dev Environment — Linux/WSL, Terminal, VS Code

Pre-read (skim before the session)

• 🎥 Intuition (5–15 min) · How to Ask Questions the Smart Way — talk — Why 'have you googled it' is a compliment, not an insult.
• 🎥 Deep dive (30–60 min) · MIT Missing Semester — Debugging and Profiling — How pros read stack traces, docs, and error messages under pressure.
• 🎥 Hands-on demo (10–20 min) · How to Read Documentation — Fireship — A rapid tour of the doc patterns you'll see everywhere.
• 📖 Canonical article · Divio — The Documentation System (Diátaxis) — The 4-quadrant model (Tutorials / How-to / Reference / Explanation) that every good doc site follows.
• 📖 Book chapter / tutorial · How to Ask Questions the Smart Way — Eric S. Raymond — Old but timeless — teaches you what a good bug report / SO question looks like.
• 📖 Engineering blog · Stripe Engineering — How we built Stripe Docs — A tour of the best developer docs on the internet, from the team who made them.

(a) Intuition · 5 min

The one-paragraph mental model. Why this concept exists, what problem it solves, and the analogy that makes it stick.

In one sentence: The single skill that unblocks every other one.

Every senior engineer looks like a wizard from the outside. What's actually happening: they have two habits juniors don't. First, when they hit an error, they read the whole error message — not just the last line, but the traceback, the file, the line number, and any hints. Second, when they don't know something, they know exactly where to look and what search terms produce answers.

Documentation is not written to be read cover-to-cover. It's a reference organised into four flavours — tutorials, how-to guides, reference, and explanation — and knowing which one you need saves hours. Tutorial when you're new; how-to when you have a specific task; reference when you know the concept but forgot the syntax; explanation when you want to understand why it works that way.

Googling is a skill. python list dedupe order preserve beats how to remove duplicates in python. site:docs.python.org itertools.groupby beats python groupby. Adding the error message verbatim (in quotes) beats paraphrasing.

Gotcha to carry forever: if you spend more than 15 minutes stuck, either write down what you've tried and ask a human, or take a 5-minute walk. Staring at the same screen doubles the debug time; a fresh look halves it.

(b) Visual walkthrough · 15 min

Diagrams, worked examples, step-by-step visuals.

The Diátaxis model of documentation — memorise this quadrant, it explains every good docs site (Stripe, Django, React, Kubernetes, Postgres):

When you're stuck, ask yourself which of the four you actually need:

Worked example — decoding a Python error:

Traceback (most recent call last):
  File "app.py", line 42, in <module>
    data = json.loads(response.text)
  File "/usr/lib/python3.12/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Read bottom-up:

1. The error name (JSONDecodeError) → the class of problem.
2. The message (Expecting value: line 1 column 1) → nothing at position 0, i.e. the string is empty or HTML instead of JSON.
3. Your code line (app.py:42) → not the library's fault; check response.text first.
4. Hypothesis: response probably has a non-200 status; you're feeding an HTML error page to json.loads.
5. Fix: print response.status_code and response.text[:200] before parsing.

Worked example — search query evolution:

(c) Hands-on · 20 min

Code you type and run. Not pseudo-code — real, runnable, copy-pasteable.

This one is 40 % code, 60 % habit-building. Do all six exercises in order — they take ~20 minutes together.

#!/usr/bin/env bash
set -euo pipefail
 
mkdir -p ~/projects/learning/s004 && cd ~/projects/learning/s004
 
# Exercise 1 — read a real error message end-to-end.
python3 - <<'PY' || true
import json
data = json.loads("not-json-at-all")
PY
# ⇒ Read the traceback. Which line raised? What class of exception?
 
# Exercise 2 — use --help for the first time on a tool you use daily.
git --help | head -30
git commit --help | head -20   # opens `man git-commit` on some systems
 
# Exercise 3 — use `tldr` for quick, example-first docs.
if ! command -v tldr >/dev/null; then
  pip install --user tldr >/dev/null
fi
tldr tar
tldr curl
 
# Exercise 4 — search the Python docs from the CLI.
python3 -c "import json; help(json.loads)" | head -30
 
# Exercise 5 — grep the actual source of a library you use.
python3 -c "import json, os; print(os.path.dirname(json.__file__))"
# Then: cd into that directory and `less __init__.py`. You CAN read library source.
 
# Exercise 6 — build a habit log of your own questions.
cat >> ~/projects/learning/s004/QUESTIONS.md <<'MD'
# Question log
 
| Date | I got stuck on… | What I tried | What fixed it | Time lost |
|---|---|---|---|---|
| 2026-07-23 | JSONDecodeError | ran `print(response.text)` | server returned HTML 502 | 10 min |
MD
cat ~/projects/learning/s004/QUESTIONS.md

Checklist — what to observe:

1. The traceback in Exercise 1 lists the file, line, and exception class before the message.
2. git commit --help opens the full man page — press q to exit, / to search.
3. tldr tar shows 5 real-world examples, not a wall of flags.
4. help(json.loads) prints the docstring — often better than google for stdlib.
5. You just discovered that json is a ~500-line Python file you can read.

Try this modification: every time you get stuck in the next 6 months, add a row to QUESTIONS.md. After a month, sort it by "time lost" descending — that's your personal skill-gap map. It's the single highest-leverage habit in this whole series.

(d) Production reality · 10 min

How this shows up in real systems, gotchas, war stories, common bugs.

War story — the "just google it" senior. A staff engineer at Netflix is famous for solving in 30 seconds problems that had a team stuck for 3 days. His secret, when asked: he copied the exact stack trace into Google, added site:github.com, and found the issue thread where the library maintainer had already explained it. Reading is a skill you can train.

War story — the RTFM that saved a launch. A team wired up AWS Lambda and hit 90-second cold starts. They spent a week trying "clever" optimisations. The launch day fix took 4 minutes: the docs' "Configuring provisioned concurrency" page had a big yellow box saying "for latency-sensitive workloads, use this." Nobody had read it. Every incident post-mortem includes "did we read the docs?" as a checkbox.

How top teams read docs:

1. Search the docs site first, not Google. Modern docs (Stripe, Anthropic, Cloudflare) have algolia search that beats Google for their own product.
2. Read the changelog when upgrading — breaking changes are called out.
3. Read the source for libraries you depend on heavily. It's usually less code than you fear.
4. Star the "Design" or "Architecture" section — it explains the why and helps you predict edge cases.

Effective help-seeking — the SSCCE rule. When you finally do ask a human (Slack, Stack Overflow, a coworker), your question should include a Short, Self-Contained, Correct, Example. Roughly: "here's what I ran, here's what I expected, here's what I got, here's what I've tried." That format triples your reply speed and shows respect. It's also the format LLMs answer best — same reason.

AI tools change the game but not the fundamentals. ChatGPT / Claude / Copilot are fantastic at "explain this error" and "give me the boilerplate for X" — but they hallucinate APIs. Rule at Microsoft, Google, and Anthropic: LLM output is a starting hypothesis, always verified against the real docs before it ships. The doc-reading skill compounds; the AI skill depends on it.

(e) Quiz + exercise · 10 min

1. Name the four Diátaxis documentation types and one example of when you'd use each.
2. When decoding a Python traceback, why do you read it bottom-to-top?
3. What information should a good bug report / Stack Overflow question include (name at least 4 items)?
4. Why is quoting an exact error message in Google usually better than paraphrasing?
5. When is it appropriate to stop debugging alone and ask a teammate?

Stretch problem (connects to S003): using only the command line, find the line number in the Python json/__init__.py source file where JSONDecodeError is raised for empty input. Hint: python3 -c "import json, os; print(os.path.dirname(json.__file__))" then grep -n "Expecting value" __init__.py decoder.py.

Explain-out-loud test

If you can't teach these 3 things to a friend without notes, redo the session:

1. What is Reading Docs & Effective Googling? (one sentence, no jargon)
2. When would you use it? (one concrete example)
3. When would you NOT use it? (one anti-pattern)

What comes next

• Next session (S005): Python Variables & Types — Mental Model of Memory
• Previous (S003): The Command Line — bash, pipes, grep, jq
• Hub: The 6-Month Learning Plan

Part of a 130-session evergreen learning series. Session structure: (a) intuition · (b) visual walkthrough · (c) hands-on · (d) production reality · (e) quiz + exercise. Duration: 60 minutes.