Writing it down for whoever is next

Whoever is next is usually you

Not a new hire. You, in eight months, after four other projects, looking at a deploy script you wrote and cannot remember the reason for. All the context that makes the system obvious today is gone by then, and none of it is recoverable from the code.

So this last lesson is about what to leave behind. It is four documents, none of them long, and it is the difference between a project that survives a gap and one that gets rewritten because nobody dares touch it.

1. README: how to run it

What this is, in two sentences. Then the commands, in order, that take a clean machine to a running local copy. Then the environment variables, with what each one is for and where to get it. Then how to run the tests.

The test for a README is not whether it is complete. It is whether someone else can follow it on a clean machine without asking you anything. Every question they have to ask is a bug in the document, and you cannot find those bugs yourself, because the two steps you left out are exactly the two you do without noticing.

2. RUNBOOK: how to operate it

Everything you would need at 3am:

• How to deploy. The exact command.
• How to roll back. The exact command, and how far back you can go.
• How to restore a backup, with the last date this was actually tested.
• Where the logs are, and how to search them.
• Each alert, what it means, and the first thing to check.
• Vendor status pages, support contacts, account details.

Write it after an incident, when you remember what you wished you had. Then it stays accurate because you keep needing it.

3. RENEWALS: what expires and on whose card

From the earlier lesson. What you pay for, where, which card, what expires when, and which role address owns the account.

4. DECISIONS: why it is like this

The shortest document and the one that saves the most damage. A handful of entries, three lines each:

Soft delete on threads, not hard delete. A legal-hold record can reference the content, and a hard delete orphans replies. See docs/09.

Client components must not import database modules. It pulls the Postgres driver into the browser bundle and 500s every page. tsc and eslint both pass while this is broken; verify:client-boundary is the check.

Without these, a reasonable person doing a reasonable cleanup deletes the guard, and everything breaks in a way that takes a day to trace. A decision with no written reason has no defence. This is the same practice as the postmortem, applied before the incident instead of after.

Access, which is not a document

The accounts must not live in one person’s personal email or personal password vault.

• Role addresses (ops@, admin@) on every vendor account, forwarding to whoever holds the role now.
• A shared password manager. Bitwarden has a free tier and Vaultwarden is a free self-hosted server that speaks the same protocol; 1Password is the paid standard.
• MFA recovery codes stored where a second person can reach them, because the more likely disaster is being locked out, not being broken into.
• Registrar and DNS access documented explicitly. They are the two that cannot be recovered by any other route.

The honest test

Ask somebody to deploy a trivial change using only the documents. Watch, and do not help. Every time they stop, you have found a gap.

If there is nobody to ask, do it yourself on a machine you have never used, with your notes closed. It is uncomfortable and it is the only reliable check available.

Where this course ends

You started with a thing that worked on your laptop. You now have a picture of how a request reaches it, a deploy that is boring and reversible, enough instrumentation to answer “is it broken and since when”, a sense of where it will fall over and what that costs, and a plan for the day it breaks.

None of it is glamorous. That is the point of the subject. Shipping is not the last step of building: it is a separate practice, made out of small boring artifacts that each prevent one specific bad evening.

Go and deploy the thing. Then roll it back once, on purpose, while nothing is wrong.