2.Margin Notes and the Cookbook

The Problem in Real Life

Knowledge in One Person's Head vs. Written Where Readers Will Find It

Comments vs. Documentation, and the Kinds of Documentation

• Comments — notes in the margin (Act 07): a comment sits next to the code and explains why: a business reason, a surprising decision, a workaround and its link. If a comment only repeats what the code does (// add 1 to count), the code should be clearer instead. A wrong comment is worse than none, so update comments when the code changes.
• Documentation — the cookbook: documentation explains, separately from the code, how to use something or how the system fits together. It's for readers who won't — or shouldn't have to — read the code.
• Function and API docs — the label on each tool: a short block above a public function describing its purpose, parameters, return value and errors, often in a standard format (JSDoc, Python docstrings). Editors show it when you hover over the function. API docs for other teams (Act 23, OpenAPI) are the same idea at a larger scale.
• README — the front door (Act 16): what this project is, how to set it up, run and test it, and where to find everything else.
• Architecture docs — the map: how the parts of the system connect: diagrams like Anna's Sale Day diagram (Act 14), what talks to what, where data lives.
• Decision records — why we chose this: an ADR (architecture decision record) is a short note: the situation, the options, the decision and its consequences. "Why do we use cursor pagination?" (Act 23) — answered once, forever.
• Runbooks — what to do at 3 AM: step-by-step instructions for operating the system and handling incidents: "if the email queue is older than 5 minutes, do this" (Act 21).
• Changelogs and release notes — what changed: a list of changes per version (Act 18), for users and other developers.
• Keeping docs alive: keep docs in the repository, next to the code, and update them in the same pull request as the change (Act 16). Write for a specific reader, put the most important thing first, use examples, and delete docs that are no longer true.

/**
 * Calculates the total price for a group booking.
 *
 * @param {number} ticketCount - Number of tickets (1–60).
 * @param {number} basePrice - Price of one ticket.
 * @param {boolean} isStudent - Whether the group is a verified student group.
 * @returns {number} Total price after any group and student discounts.
 */
function calculateGroupPrice(ticketCount, basePrice, isStudent) {
  // ...
  // Student discount applies AFTER the group discount, as agreed with venues
  // (pricing decision, 2026-09). Applying it first would over-discount large groups.
}