S004 · Reading Docs & Effective Googling — the Meta-Skill
The single skill that separates a 10× engineer from a 1× engineer: knowing how to find the answer, fast, without asking a human. Man pages, official docs, GitHub source-diving, and search queries that actually work.
🎯 Find any answer about any tool, library, or bug in under 5 minutes — using docs, source, and search queries that pros actually use.
Why this session exists
Every engineer, from L1 to Distinguished, spends most of their day finding out things they don't know. The gap between "senior" and "junior" is rarely about knowledge; it's about how fast they can close the gap when they don't know something. A senior finds the answer in the source in 3 minutes. A junior googles in circles for an hour and then asks in Slack. This session teaches the meta-skill: how to read docs, navigate source, and craft a Google/GitHub/DuckDuckGo query that actually finds the thing you need.
- Read a `man` page top-to-bottom and know which section is worth your time (SYNOPSIS, EXAMPLES, EXIT STATUS).
- Craft search queries with `site:`, `after:`, exact-string, and negative filters that surface the exact answer.
- Navigate a stranger's GitHub repo — README → docs/ → src/ → tests/ — and find where a feature is implemented in \<10 minutes.
- Use `--help`, `tldr`, `cheat`, and `zeal`/`Dash` offline docs to answer 80% of ‘what does this flag do?’ questions without opening a browser.
- Know when the docs are lying and it's time to read the actual source.
Prerequisites
- S001 — Dev Environment · a working shell
- S002 — Git & GitHub · you'll clone repos to search their source
- S003 — The Command Line ·
grep/rgfor searching source
(a) Intuition · 5 min
You don't read a library. You walk in with a specific question, find the aisle, pull one book, flip to the index, read three paragraphs, and leave. Trying to read the whole reference is a beginner mistake — the same beginner mistake as trying to memorise a dictionary before speaking a new language.
Every senior engineer treats docs the same way: skim the table of contents, scan for the section that matches your question, and read only what you need.
Concretely: every well-structured doc site has the same four kinds of pages — Diátaxis calls them tutorials, how-to guides, reference, and explanation. Knowing which kind you need makes the difference between finding your answer in 30 seconds and reading for an hour.
Search queries are the same. A precise query returns the answer on page 1. A vague query returns 40 million Stack Overflow posts, none of them yours.
The four kinds of doc pages (Diátaxis)
- Tutorials — ‘let me build my first X, step by step’. Good for learning; bad for reference. Read once, never return.
- How-to guides — ‘I have a specific problem, show me the recipe’. Reach for these when you already know the tool but need to do a specific thing.
- Reference — ‘what are the exact parameters of function foo?’ Terse, precise, generated. This is where you spend 80% of your doc time.
- Explanation — ‘WHY does this tool work this way?’ Read once per tool, when you're first onboarding. Ignored later.
A quick history of ‘how devs found answers’
- 1971man pagesUnix ships with `man` — the first offline, searchable, structured docs. Still on your machine today. Still useful.
- 1998Google launchesPageRank makes ‘search for the answer’ actually work. Kills IRC as the primary support channel.
- 2008Stack OverflowJeff Atwood + Joel Spolsky invent the ‘one question, one accepted answer’ format. Peak signal-to-noise for ~10 years.
- 2018GitHub Code SearchYou can now grep the entire open-source universe. Reading the source of a library is faster than reading its docs.
- 2023LLMs as docsChatGPT / Claude / Copilot become the ‘first draft’ for many devs. Docs and source remain the ground truth — LLMs hallucinate.
(b) Visual walkthrough · 15 min
The doc-hunting funnel
Read that top-to-bottom. Each level is faster and higher-signal than the one below. Stack Overflow and LLMs are not the first place to look — they are the fourth and fifth. Juniors invert this funnel and pay for it every day.
Anatomy of a man page (worth memorising)
Sections of `man <tool>` in the order you should read them
Google/DuckDuckGo query operators every dev should know
Cut noise from the top of results
- "exact phrase" — quotes force an exact substring match
- site:docs.python.org — only that domain
- -medium.com -w3schools.com — negate low-signal sites
- after:2023 — only recent results (for changing tools)
- filetype:pdf — for papers and books
‘why is my python slow’
- 12M results
- Stack Overflow from 2011
- Beginner tutorials
- Ads
- No answer in the first 3 pages
Same question, senior form
- ‘cpython list append amortized site:docs.python.org’
- ‘python 3.12 gil release notes’
- ‘"async def" pattern for i/o-bound site:realpython.com’
- 3 results, all correct, top of page
GitHub Code Search — the underrated superpower
`"raise RuntimeError("loop already running""` — find every project that ever emitted that error.
`language:python "asyncio.get_event_loop()"` — only python files.
`repo:torvalds/linux "panic("` — only inside the Linux kernel.
`path:tests/ "parametrize"` — only test files.
`symbol:parse_url language:python` — jump to every definition of parse_url in Python code.
When online search hits limits, `git clone --depth=1 <repo>` and `rg -tpy 'pattern'`.
The mental model to hold
"Reading docs is the slow path. Searching gets me an answer in 30 seconds and copying a working Stack Overflow answer is the same thing as understanding it."
Search gives you an instance; docs give you the space. A search result answers the question you managed to phrase; the reference tells you which questions are askable at all — including the parameter that makes your whole workaround unnecessary.
Because for the first year of a technology the tradeoff genuinely favours search. Common problems have been solved publicly, the top result usually works, and reading a reference page costs ten minutes to answer a one-minute question. What that habit hides is the failure mode that arrives later: you cannot search for a feature whose name you do not know. Engineers who only ever search end up reimplementing things that already existed as a flag — hand-rolled retry loops next to a built-in retries=, manual chunking next to a chunksize= parameter, a custom backfill next to an idempotent upsert mode. The search worked perfectly every time; it just never told them what they were missing.
Try it on a library you think you know. The gap between these two numbers is your blind spot:
import pandas as pd, inspect
sig = inspect.signature(pd.read_csv)
print(len(sig.parameters)) # how many knobs exist
print(list(sig.parameters)[:20]) # how many you have ever used
# and the version-specific truth, which no blog post has:
print(pd.__version__)
help(pd.read_csv)Why is the official reference so often harder to read than a blog post, yet the only source you can trust? This is not laziness by the maintainers — it follows from what a reference has to be.
- 1A reference must describe every legal input and every guaranteed behaviour of an API, because it doubles as the contract the maintainers are bound by.forced by · anything omitted from the contract is something users will rely on and maintainers will break
- 2Completeness forces the text to be organised by API surface — module, class, parameter — not by the tasks a reader has in mind.forced by · there are finitely many parameters but unbounded many tasks; only one of those can be enumerated
- 3A tutorial or blog post has the opposite constraint: it optimises for one task, so it may omit everything irrelevant to that task, including the caveats.forced by · narrative flow requires cutting the 95% of the API the reader doesn't need right now
- 4But a blog post is a snapshot taken on a date, against a version, by someone with no obligation to update it. The reference is regenerated from the source of the version you are actually running.forced by · docstrings live in the same repo as the code and move with it; a blog post does not
Therefore the two are not competitors, they are different data structures over the same knowledge: the tutorial is an index optimised for intent, the reference is optimised for truth and completeness. Use the tutorial to learn the shape, then verify against the reference for your exact version.
And note what this predicts: the moment a blog post and the docs disagree, the docs win — but only if you checked the version selector. It also predicts where the highest-value reading is: the "Notes", "Warnings", and "Changed in version X" boxes, because those are precisely the parts no tutorial ever reproduces, and the parts that cause production surprises.
Every documentation set answers four different questions, and almost all frustration comes from knocking on the wrong door. Tutorial: I am new, teach me. How-to: I have a specific goal, give me steps. Reference: I need the exact contract. Explanation: I want to know why it was designed this way.
Before reading anything, name which of the four you actually need. "The docs are bad" is usually "I opened the reference wanting a how-to."
- Stuck on how → how-to or a search. Stuck on what exactly → reference. Stuck on why is it like this → design docs, changelogs, GitHub issues, PEPs/RFCs.
- Always pin the version. Doc sites default to
latest; you are almost never on latest. - When the docs run out, the source is documentation:
inspect.getsource, the tests directory, and the issue tracker. Tests are executable specs and are frequently clearer than prose. - Search queries should carry the error verbatim plus the library and version, and should exclude your own identifiers — those are unique to you and poison the results.
Fire this model the moment you see: a third contradictory Stack Overflow answer · a snippet that fails with "unexpected keyword argument" · "the docs don't explain this" · an LLM answer using an API that does not exist · behaviour that differs between your laptop and prod.
You are blocked on an unfamiliar library. Do you search, read the reference, read the source, or ask a human?
Timebox search, then escalate to the reference — and always verify a searched answer against the docs before it reaches a code review. The senior habit is not "read everything"; it is noticing fast when search has stopped converging and switching sources instead of running the same query with different words.
When you do ask a human, ask well: state what you tried, what you expected, what happened, and the version. That turns a 20-minute conversation into a 2-minute one, and it frequently answers the question while you are writing it down.
(c) Hands-on · 25 min
Work through this yourself, one command at a time. No script — the whole point is that you build the muscle memory. Save answers in a scratchpad.
# S004 · doc-hunting drills.
# Time yourself. Aim: each question in under 3 minutes.
# --- Drill 1: local docs are always faster ---
# Q1a) What does `curl -f` do? (find the exact wording)
curl --help | grep -A1 -- '-f,'
# Q1b) What flag makes curl follow redirects? (search the man page)
man curl | less # then type: /follow (press n to jump next hit)
# Q1c) Every dev should install `tldr` — condensed community examples
sudo apt install -y tldr || brew install tldr # then:
tldr curl
tldr tar
tldr find
# --- Drill 2: official docs, right level ---
# Q2a) How do you type-annotate a dict-of-lists in Python?
# → docs.python.org/3/library/typing.html — search for `dict[`
# Q2b) In npm, what is the difference between `install` and `ci`?
# → docs.npmjs.com — look at the CLI Commands reference
# Q2c) What are the top-level fields of a Kubernetes Deployment YAML?
# → kubernetes.io/docs/reference — look for the API Reference (NOT the tutorial)
# --- Drill 3: search a real repo like a pro ---
# Q3a) How does React implement useState internally?
# → github.com/facebook/react — Code Search: `symbol:useState language:javascript path:packages/react/`
# Q3b) Which file in the Linux kernel handles the `sched_yield` syscall?
# → github.com/torvalds/linux — Code Search: `symbol:sched_yield`
# Q3c) In pandas, where is the actual code for DataFrame.merge?
# → clone locally, then:
# git clone --depth=1 https://github.com/pandas-dev/pandas /tmp/pandas
# rg -n "def merge" /tmp/pandas/pandas/core/frame.py | head -5
# --- Drill 4: craft a precise Google query ---
# Bad: "python threading slow"
# Good: "python 3.12 GIL removal PEP 703 site:python.org"
# Good: "sqlalchemy 2.0 select().where() vs filter_by site:docs.sqlalchemy.org"
# Bad: "aws lambda cold start"
# Good: "aws lambda cold start provisioned concurrency site:aws.amazon.com after:2023"
# --- Drill 5: when the doc site is bad, use SO — filtered ---
# Bad: "python decorator @property not working"
# Good: "python @property setter not called site:stackoverflow.com after:2022 score:5"
# → Stack Overflow supports score: filters. Skip the wrong answers.
# --- Drill 6: LLMs as first draft, source as ground truth ---
# Prompt an LLM: "Give me a fastapi middleware that logs request bodies larger than 1MB"
# Then: verify against fastapi.tiangolo.com and search Starlette's source for `BaseHTTPMiddleware`.
# Rule: if the LLM's code references a class or method, `rg` for it in the actual repo.The anatomy of a good query
Why the ‘good’ queries above beat the ‘bad’ ones
Pick a library you have never used (e.g. httpx, polars, pydantic). Answer these three, using only docs + source (no LLM):
- How do you install it and what's the minimum viable ‘hello world’?
- What is one non-obvious feature the docs are proud of? (look at the front page of the docs — they'll be shouting about it)
- Where in the source is the main entry point implemented? (
rg -n 'def __init__' src/ | head, or Code Search forsymbol:<main class>)
Write the answers in a scratchpad. Bonus: do the same drill weekly for a month. You will feel a step-change in confidence.
Six tools every senior dev has installed
- tldr — community-driven condensed man pages. `tldr find` is 100× more useful than `man find` for common cases.
- ripgrep (rg) — 10-100× faster than grep, respects .gitignore. Alias `grep=rg` if you dare.
- fd — sane find replacement.
- bat — cat with syntax highlighting and git diff markers.
- zoxide — smarter `cd`; `z proj` jumps to any dir you've visited that contains ‘proj’.
- fzf — fuzzy finder. Bind to Ctrl-R for history search that will change your life.
(d) Production reality · 15 min
A team debugging a mysterious S3 upload failure spent two days blaming their code, then their network, then AWS. It turned out the object key had a leading slash — S3 accepts it but treats the leading slash as literally part of the key, so downstream tooling that expected ‘folder/file’ got ‘/folder/file’.
The exact behaviour is documented on the first page of the S3 developer guide, under a bold ‘Important’ callout.
Strip the leading slash. One-line code change. Two days of investigation avoided by reading the first page of the docs before writing any code.
Cursor / ChatGPT / Copilot cheerfully generates code that calls boto3.client('s3').download_file_stream(...). Beautiful, plausible, exactly what the dev wanted. It does not exist. The real method is get_object()['Body'].iter_chunks().
Junior devs paste the fake code, get an AttributeError, ask the LLM to fix it, and the LLM invents a new fake method. Loop for two hours.
Rule: any LLM-generated code that references a library method — look up the method in the docs or source before running it. `rg 'def <method>' <repo>/` takes 5 seconds and always tells the truth.
Better: use tools that ground their suggestions in the actual installed package (e.g. Copilot with recent context, Cursor with docs indexing).
Write a good bug report: expected vs actual, exact commands, exact versions (tool --version, OS, Python version), full stack trace in a code block, and a minimal reproducer that the maintainer can copy-paste.
See ‘How to Ask a Good Question’ by Simon Tatham — same rules apply to mailing lists, Slack, and colleagues.
Where this shows up in the rest of the plan
(e) Recall + stretch · 10 min
Explain-out-loud test
If you can't teach these three without notes, redo the session:
- What are the four Diátaxis types of docs? (name them, one sentence each)
- What's the doc-hunting funnel? (list the six levels in order)
- Why can't you trust an LLM's code without verifying? (one concrete failure mode)
What comes next
Hub: The 6-Month Learning Plan
Part of a 130-session evergreen learning series. Session structure: intuition → visual → hands-on → production war stories → recall. Duration: 90 minutes.