Chapter 13 · Reps

Documentation Is a Deliverable — Reps

← Back to Chapter 13

Chapter 13 — Reps

These reps are not warm-ups. Each one produces a piece of the documentation set that Milestone 13 grades, in the order that makes the next piece easier. By the end of Rep 11 the set exists; the capstone rep rehearses the clean-machine test so the graded run is not the first time you have seen your own instructions fail.

Ground rules

  • Work on YOUR repository. Every rep operates on the real project you have been building for twelve weeks — not a sample, not PantryPilot.
  • Nothing counts until you have run it. A command you typed into a document but did not execute is a claim, not documentation.
  • Paste real output. Not what you remember it saying. Copy it from the terminal.
  • Placeholder secrets only. sk-REPLACE_ME, <your-api-key>, .env.example. If a real credential ever reached a commit, rotate it — deleting the line does not remove it from history.
  • Commit as you go. One artifact, one commit, a message that says what changed. docs: add runbook failure catalogue from defect log beats updates.
  • Log AI use honestly. Anything an assistant drafted gets a row in docs/ai-usage.md, including what you found wrong when you ran it.
  • Reflections in plain prose. Two to four sentences. A rep is not done until the reflection is written.

Group A — Diagnose what you actually have

Rep 1 — Score your README before you touch it

Open README.md as it stands right now. No cleanup first — the point is the honest baseline. Score each of the eleven sections: 2 = present and complete, 1 = present but thin or vague, 0 = missing.

 1. What it is / who it is for     ___
 2. Demo (screenshot, GIF, session) ___
 3. Prerequisites with versions     ___
 4. Install                         ___
 5. Configure                       ___
 6. Run (+ the action that proves it works) ___
 7. Test                            ___
 8. Project layout                  ___
 9. Troubleshooting                 ___
10. License                         ___
11. Contact / further reading       ___
                            TOTAL: ___ / 22

Then do the same in the README Grader widget on the chapter page and compare the two numbers.

Reflect: Where did you score yourself higher than the widget did, and why? The gap between your score and an outside score is the exact size of your curse of knowledge.

Rep 2 — Pin what you actually have

Stand in the directory where the project works and print real version strings for every tool it needs.

node --version ; npm --version ; psql --version ; git --version
# substitute your stack's tools — python3, java, go, docker, whatever you actually use

Paste the real output into a prerequisites table with three columns: requirement, tested-on version, check command. Then add the row nobody writes: for each prerequisite, what breaks and how the reader will recognize it.

Reflect: Which prerequisite did you almost forget because it has been installed on your machine since freshman year? Those are the ones a stranger cannot guess.

Rep 3 — Find the invisible accounts and the personal paths

Two passes. First, the mechanical one:

grep -rnE "/litman-books/Users/|/home/[a-z]|C:\\\\Users|localhost:[0-9]{4}|127\.0\.0\.1" README.md docs/

Second, the one only you can do. List every external thing your project depends on that installs nothing: an API key, a database you created by hand in a GUI, an OAuth application registered under your personal account, a table you seeded manually and never scripted, a webhook pointed at your laptop.

| External dependency | Where you get it | Free? (verify with vendor) | What happens without it |
|---|---|---|---|

Reflect: How many invisible dependencies did you find, and which one would have stopped a stranger cold within five minutes?

Group B — Write the set

Rep 4 — Every command gets an expected result

Rewrite the Install / Configure / Run sections of README.md so that every command is followed by what success looks like. Run each one as you write it.

{{command}}

Expected: {{the real last line of successful output}} — takes about {{N}} seconds. If you see {{the common failure}}, {{the fix}}.

Finish with the verification action: one concrete thing a stranger can do to prove the system works, not merely that it started.

Reflect: Which command’s real output surprised you — a warning you had stopped seeing, a prompt you answer automatically, a line that looks like an error but is not? Write down what you had trained yourself to ignore.

Rep 5 — The architecture overview, timeboxed to 45 minutes

Set a timer. Produce docs/architecture.md: one diagram (four to eight boxes, every arrow labeled) and five paragraphs — what the system does, the components and what each owns, the data and what is authoritative, one end-to-end flow traced through every box, and the consequential decisions with links to their ADRs.

The fifth paragraph must end with the sentence: “The thing that would surprise a new reader is ___.”

Reflect: What is the surprise, and how long had it been in your system undocumented? Would you have remembered it in Week 16?

Rep 6 — Five runbook entries, mined from your defect log

Open docs/defect-log.md from Week 11. Pick the five defects most likely to recur — the outages, the config mistakes, the third-party failures. Convert each into a runbook entry using code/runbook-template.md:

### F-0N — <symptom in the operator's words>
- Symptom:            <exact error text>
- First check:        <command> → healthy looks like <output>
- Likely cause:       <cause, with the defect number it came from>
- Fix:                <command or steps>
- Verify:             <the check that should now pass>
- If that fails:      <next step, or STOP and escalate>

At least one entry must name a destructive command the operator must not run.

Reflect: Which of the five did you have to go look up because you no longer remembered how you fixed it? That is your bus factor talking.

Rep 7 — The feature-to-code map and one real first issue

Write the two sections of docs/onboarding.md that a newcomer uses first.

| Feature a user would name | Where it lives | Its test |
|---|---|---|
| ... | ... | ... |      (five rows, real paths)

Then pick a genuinely useful, genuinely small task from your backlog and write it up: the file to open, the test to run, what “done” looks like, and roughly how long it should take. Then leave it undone.

Reflect: Could a competent stranger finish that issue in under an hour using only what you wrote? If not, what did you assume they already knew?

Rep 8 — The ADR index, and the decision nobody recorded

Build docs/adr/README.md as a table: number, decision in one line, status (Proposed / Accepted / Superseded by NNNN / Deprecated), and the consequence a reader would notice. Mark every superseded record honestly; delete nothing.

Then find the decision with no record. There is one — something you chose fast, under pressure, sometime after Week 8, that has shaped everything since. Write the ADR now, dated when you actually made it, with the context and alternatives you actually had.

Reflect: Why did that decision never get written down at the time? Was it too obvious, too rushed, or too uncomfortable to defend?

Group C — Verify

Rep 9 — Run the linter, then argue with it

python3 doc_lint.py README.md
python3 doc_lint.py docs/runbook.md

Use code/doc_lint.py. Fix every ERROR. Read every WARN and decide.

Reflect: Name one thing it flagged that you decided was a false positive, and defend the decision in two sentences. A tool you obey blindly is as bad as a tool you ignore.

Rep 10 — Let an assistant draft, then count what was wrong

Give an assistant your docs/defect-log.md and your README and ask it to draft a troubleshooting table. Then run every command it produced, in order, on your machine.

| # | Command the assistant wrote | Ran it? | Correct? | What was actually wrong |
|---|---|---|---|---|

Write the row for docs/ai-usage.md: tool used, what it drafted, how many of its commands required correction, and what you did about it. Report the count exactly.

Reflect: What kind of thing did it get wrong — paths, versions, flags, expected output, or things that were true three commits ago? That pattern is the failure mode you will keep meeting for the rest of your career.

Rep 11 — Document the part that can change without your code changing

If your project calls a hosted model, write the successor-facing section of docs/ai-usage.md: what the feature does and what it does when it fails, the exact model identifier and the date you pinned it, the file the prompt lives in, the parameters, cost measured by you on a stated date with a plain note that pricing changes, and — the important one — what must not be assumed stable.

If your project has no AI feature, do exactly the same for your most volatile third-party dependency: the payment API, the map service, the auth provider, the scraper target. Same six fields, same discipline.

Reflect: If that vendor changed its behavior tomorrow, what in your system would break first, and how long would a successor take to figure out why?

Done? One Last Thing.

The dress rehearsal. You run the clean-machine test on yourself before you run the graded one on somebody else — because the graded run should not be the first time you watch your instructions fail.

  1. Get a genuinely clean environment: a fresh container, a fresh cloud development environment, or a brand-new user account on your machine. Nothing your project installed may already be there. (Appendix A has the options, including the no-admin browser path.)
  2. Open code/clean-machine-protocol.md, copy it into your repository as docs/clean-machine-test.md, and write your acceptance action at the top before you start.
  3. Start a stopwatch. Clone the repository fresh. From here on, you may read only what is in the repository — no shell history, no notes, no memory. If you catch yourself typing something the docs do not say, stop and log it as a friction entry.
  4. Reach the acceptance action, or hit sixty minutes. Record the time either way.
  5. Fix every friction entry in the documents, commit, and note which document changed.

If your solo run takes more than twenty minutes, the graded run with a real tester will fail — go fix the top three friction entries before you recruit anyone. If it takes under fifteen and you honestly used nothing but the repository, you are ready for a real tester.

One warning, because everyone gets caught by it: you will unconsciously cheat. You will type a command from muscle memory, land in the right directory by habit, answer a prompt without reading it. That is not a character flaw; it is the curse of knowledge doing exactly what it does. The fix is mechanical — narrate each step out loud as “the README says to…”, and if you cannot finish that sentence, you have found a friction entry.

Up next: Milestone 13