The Professor
Index Course index

Module 11 · Non-technical skills

Lesson 48 — Documentation and ADRs

Recording design decisions so nobody (including you) has to guess.

Published
In this lesson
  1. Exercise 1 — The docs map
  2. Exercise 2 — The course's ADRs
  3. Exercise 3 — The living reference
  4. Exercise 4 — The expiry
  5. Exercise 5 — The onboarding
  6. Submit

The project's memory, written down. No solutions.md before submitting.

Exercise 1 — The docs map

  1. Audit YOUR current documentation: what format does each doc have (tutorial/how-to/reference/explanation)? Which one mixes everything into a 500-line README?
  2. Reorganize (or design) the docs/ with §1's structure: the 4 directories, 2 minimum docs each (the "nuevo-endpoint" how-to and the events reference are mandatory).
  3. The reader test: for each new doc, write in the PR the reader's question it answers ("how do I do X?"). If a doc answers 3 questions: split it.

Exercise 2 — The course's ADRs

  1. Write the 3 ADRs that marked you most from the index (§3) in the full format (context with numbers, decision, +/− consequences, review trigger, Supersede if applicable).
  2. The index: create docs/adr/README.md with the course's decision table (§3's 12 + yours) — each row linking to the ADR and the lesson that originated it.
  3. The Supersede chain: simulate the decision change (Kafka for ×10 volume?): write ADR-0018 replacing 0011 (new context, new decision, the link to the old one with its "superseded" status). What happens to the old one (deleted? edited? the answer is in §2).

Exercise 3 — The living reference

  1. 45's events reference: turn it into the documented source of truth (event/keys/level/emitter table) and add the test validating it: the code's event catalog and the doc must match (a test reading both and failing if they diverge — §4's doc-linked-to-code).
  2. The API: verify 15's reference (drf-spectacular) regenerates in 41's pipeline and the doc links to the generated schema (never hand-copied).
  3. 27's settings: the environment-variable reference generated FROM the settings (.env.example as the source) — how do you keep doc and code from diverging? Implement the mechanism (test or generation).

Exercise 4 — The expiry

  1. Add the review header to ALL your docs (Last reviewed, owner) and 31's quarterly task (or the CI check: the doc unreviewed for 6 months flags a build warning — implementable with a 20-line script).
  2. The doc-linked-to-code: pick 2 statements of your docs that CAN be tests (39's "listings carry no total", 38's "availability is not cached in checkout") and create the tests guarding them. The doc gets linked to the test by name.
  3. The repo's README: rewrite it with the Diátaxis matrix: 30 lines maximum with the 4 links (onboarding, howtos, reference, ADRs) — the door, not the house.

Exercise 5 — The onboarding

  1. Write docs/onboarding.md (the day-1 tutorial): clone → 40's compose → seed → the first green test → the ADR tour. The tutorial's test: does a teammate (or you on a clean machine) finish day 1 with the system running and a PR made?
  2. The real proof: follow YOUR onboarding in a clean environment (or simulate it step by step): how many steps were missing? Fix the doc with what you discovered (the untested doc is fiction).
  3. The module's close: the list of "the 5 documentation pieces that served you most in the course" (47's runbook? 43's ADR? 27's.env.example?) — the personal rule of what you document first when time is tight.

Submit

Paste the docs/ structure, 3 full ADRs, the doc↔code test and the proven onboarding. Next: Lesson 49 — Estimating and splitting problems.

^ top