Foundations — Documentation — inline comments, docstrings, README, ADRs

Before you can appreciate inline comments, docstrings, README, and ADRs, you need to be fluent in a surprising number of tiny words and symbols the parent note throws around. Below we build every one of them from nothing, in an order where each rung of the ladder rests on the one below it.

0. What is "a program" and who reads it?

Picture two readers standing in front of the same text file:

• The machine (left) cares only about what to do. It never reads the English notes you sprinkle around; it strips them out.
• The human (right) — a teammate, or you in six months — needs why it exists and how to use it.

Why the topic needs this: the whole subject exists because these two readers want different things. Documentation is text written exclusively for the human reader. If you forget the human exists, none of the four layers make sense.

1. The read/write ratio — the symbol 10:1

The picture is a simple tally:

One amber mark for writing; ten cyan marks for reading (running it, debugging it, extending it, reviewing it, copying from it).

Why this tool and not another? We use a ratio rather than an absolute count because the exact numbers don't matter — what matters is the imbalance. A ratio captures "reading dominates" in two symbols. This single fact is the economic engine of the whole topic: a small cost paid once (writing a note) is repaid on every future read.

2. "Scope" — the zoom ladder

Think of a camera zooming out. As the frame widens, two things change together: the audience gets broader and less familiar, and the question changes.

Why the topic needs this: the four documentation layers are exactly these four zoom levels. Understanding "scope" first means the four layers stop looking like a random list and become one continuous ladder.

3. WHAT vs WHY — the two questions

Why the topic needs this: the golden rule of inline comments — "explain the why, never the what" — is meaningless until you can cleanly separate these two words. Every mistake in comment-writing is really a WHAT-vs-WHY confusion.

4. "Contract" — pre/post/failure

The picture is a handshake with a rulebook between two parties:

Why this tool and not another? We borrow the word contract from law because it captures the key idea: you can use the function without reading its insides, as long as both sides honour the agreement. A docstring is simply this contract written down. Later notes on API Design & Contracts lean on exactly this vocabulary.

5. Notation you'll meet — small symbols decoded

6. Two words for a project's history

The picture is a stack of dated cards you only ever place on top:

Why the topic needs this: ADRs are immutable, append-only records. When a decision changes, you do not edit ADR-007 — you write ADR-015 that supersedes it. Without the words "immutable" and "append-only" the phrase "we never edit an old ADR" sounds like a bug rather than the entire point.

The prerequisite map

Read it bottom-up: the machine-vs-human split feeds both the economics (why bother) and the scope ladder (the four layers); the contract idea feeds docstrings; the log idea feeds ADRs. All four streams pour into the Documentation topic itself.

Connections to build next

• Clean Code & Naming and Self-documenting Code — the "rename instead of comment" reflex.
• API Design & Contracts — the contract vocabulary, deepened.
• Sphinx & Doc Generation — tools that read __doc__ to build docs automatically.
• Markdown — the text format READMEs and ADRs are written in.
• Architecture & System Design — the decisions ADRs record.
• Onboarding & Bus Factor — the human cost documentation reduces.

Equipment checklist

Cover the right side and answer each aloud before revealing.