{"course":{"slug":"cloud-and-shipping","title":"Shipping It","url":"https://addaly.com/learn/cloud-and-shipping","level":"intermediate","track":"build"},"lesson":{"slug":"handing-it-over","title":"Writing it down for whoever is next","url":"https://addaly.com/learn/cloud-and-shipping/handing-it-over","position":48,"of":74,"minutes":9,"answer":"Four short documents (how to run it, how to operate it, what expires, and why it is like this) are what turn a running site into something somebody else can keep alive.","keyIdea":"Four short documents (how to run it, how to operate it, what expires, and why it is like this) are what turn a running site into something somebody else can keep alive."},"body":{"format":"markdown","text":"## Whoever is next is usually you\n\nNot 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.\n\nSo 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.\n\n## 1. README: how to run it\n\nWhat 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.\n\nThe 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.\n\n## 2. RUNBOOK: how to operate it\n\nEverything you would need at 3am:\n\n- How to deploy. The exact command.\n- How to roll back. The exact command, and how far back you can go.\n- How to restore a backup, with the last date this was actually tested.\n- Where the logs are, and how to search them.\n- Each alert, what it means, and the first thing to check.\n- Vendor status pages, support contacts, account details.\n\nWrite it after an incident, when you remember what you wished you had. Then it stays accurate because you keep needing it.\n\n## 3. RENEWALS: what expires and on whose card\n\nFrom the earlier lesson. What you pay for, where, which card, what expires when, and which role address owns the account.\n\n## 4. DECISIONS: why it is like this\n\nThe shortest document and the one that saves the most damage. A handful of entries, three lines each:\n\n> **Soft delete on threads, not hard delete.** A legal-hold record can reference the content, and a hard delete orphans replies. See docs/09.\n\n> **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.\n\nWithout 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.\n\n## Access, which is not a document\n\nThe accounts must not live in one person's personal email or personal password vault.\n\n- Role addresses (`ops@`, `admin@`) on every vendor account, forwarding to whoever holds the role now.\n- 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.\n- MFA recovery codes stored where a second person can reach them, because the more likely disaster is being locked out, not being broken into.\n- Registrar and DNS access documented explicitly. They are the two that cannot be recovered by any other route.\n\n## The honest test\n\nAsk somebody to deploy a trivial change using only the documents. Watch, and do not help. Every time they stop, you have found a gap.\n\nIf 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.\n\n## Where this course ends\n\nYou 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.\n\nNone 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.\n\nGo and deploy the thing. Then roll it back once, on purpose, while nothing is wrong."},"check":{"question":"You write a thorough README and hand the project to a colleague, who gets stuck twice and asks you for help both times. What does that tell you?","options":[{"text":"They lacked the background knowledge the README reasonably assumes","correct":false,"tempting":"Sometimes true, and still the wrong first conclusion; assumed knowledge that stops a competent person is precisely the thing the document should have named."},{"text":"The README is fine, and their questions belong in a separate troubleshooting guide","correct":false,"tempting":"Splits the document rather than fixing it, and the reader who got stuck would not have known to look in the second file."},{"text":"The project is unusually complex, and some handover friction is unavoidable","correct":false,"tempting":"Explains the friction away instead of using it, and discards the only test of the document you will ever get for free."},{"text":"The two questions are two bugs in the README, and they are ones you could not have found yourself because you do those steps without noticing","correct":true}]},"prev":{"slug":"practising-failure","title":"Breaking it on purpose, on a Tuesday","url":"https://addaly.com/learn/cloud-and-shipping/practising-failure"},"next":{"slug":"a-model-is-a-process-with-weights","title":"A prediction endpoint is a web service with a large secret","url":"https://addaly.com/learn/cloud-and-shipping/a-model-is-a-process-with-weights"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Writing it down for whoever is next', in Shipping It. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/cloud-and-shipping/handing-it-over (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Writing it down for whoever is next","courseTitle":"Shipping It","module":{"index":5,"slug":"staying-alive","title":"Staying alive: the bad day and the day after"},"answer":null,"keyIdea":"Four short documents (how to run it, how to operate it, what expires, and why it is like this) are what turn a running site into something somebody else can keep alive.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"whoever-is-next-is-usually-you","runs":[{"text":"Whoever is next is usually you"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"1-readme-how-to-run-it","runs":[{"text":"1. README: how to run it"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"The test for a README is not whether it is complete. It is whether "},{"text":"someone else can follow it on a clean machine without asking you anything.","b":true},{"text":" 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."}]},{"t":"h2","id":"2-runbook-how-to-operate-it","runs":[{"text":"2. RUNBOOK: how to operate it"}]},{"t":"p","runs":[{"text":"Everything you would need at 3am:"}]},{"t":"ul","items":[[{"text":"How to deploy. The exact command."}],[{"text":"How to roll back. The exact command, and how far back you can go."}],[{"text":"How to restore a backup, with the last date this was actually tested."}],[{"text":"Where the logs are, and how to search them."}],[{"text":"Each alert, what it means, and the first thing to check."}],[{"text":"Vendor status pages, support contacts, account details."}]]},{"t":"p","runs":[{"text":"Write it after an incident, when you remember what you wished you had. Then it stays accurate because you keep needing it."}]},{"t":"h2","id":"3-renewals-what-expires-and-on-whose-card","runs":[{"text":"3. RENEWALS: what expires and on whose card"}]},{"t":"p","runs":[{"text":"From the earlier lesson. What you pay for, where, which card, what expires when, and which role address owns the account."}]},{"t":"h2","id":"4-decisions-why-it-is-like-this","runs":[{"text":"4. DECISIONS: why it is like this"}]},{"t":"p","runs":[{"text":"The shortest document and the one that saves the most damage. A handful of entries, three lines each:"}]},{"t":"quote","runs":[{"text":"Soft delete on threads, not hard delete.","b":true},{"text":" A legal-hold record can reference the content, and a hard delete orphans replies. See docs/09."}]},{"t":"quote","runs":[{"text":"Client components must not import database modules.","b":true},{"text":" It pulls the Postgres driver into the browser bundle and 500s every page. "},{"text":"tsc","code":true},{"text":" and "},{"text":"eslint","code":true},{"text":" both pass while this is broken; "},{"text":"verify:client-boundary","code":true},{"text":" is the check."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"access-which-is-not-a-document","runs":[{"text":"Access, which is not a document"}]},{"t":"p","runs":[{"text":"The accounts must not live in one person’s personal email or personal password vault."}]},{"t":"ul","items":[[{"text":"Role addresses ("},{"text":"ops@","code":true},{"text":", "},{"text":"admin@","code":true},{"text":") on every vendor account, forwarding to whoever holds the role now."}],[{"text":"A shared password manager. "},{"text":"Bitwarden","b":true},{"text":" has a free tier and "},{"text":"Vaultwarden","b":true},{"text":" is a free self-hosted server that speaks the same protocol; 1Password is the paid standard."}],[{"text":"MFA recovery codes stored where a second person can reach them, because the more likely disaster is being locked out, not being broken into."}],[{"text":"Registrar and DNS access documented explicitly. They are the two that cannot be recovered by any other route."}]]},{"t":"h2","id":"the-honest-test","runs":[{"text":"The honest test"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"where-this-course-ends","runs":[{"text":"Where this course ends"}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"p","runs":[{"text":"Go and deploy the thing. Then roll it back once, on purpose, while nothing is wrong."}]}],"check":{"question":[{"text":"You write a thorough README and hand the project to a colleague, who gets stuck twice and asks you for help both times. What does that tell you?"}],"options":[{"text":[{"text":"They lacked the background knowledge the README reasonably assumes"}],"correct":false,"tempting":[{"text":"Sometimes true, and still the wrong first conclusion; assumed knowledge that stops a competent person is precisely the thing the document should have named."}]},{"text":[{"text":"The README is fine, and their questions belong in a separate troubleshooting guide"}],"correct":false,"tempting":[{"text":"Splits the document rather than fixing it, and the reader who got stuck would not have known to look in the second file."}]},{"text":[{"text":"The project is unusually complex, and some handover friction is unavoidable"}],"correct":false,"tempting":[{"text":"Explains the friction away instead of using it, and discards the only test of the document you will ever get for free."}]},{"text":[{"text":"The two questions are two bugs in the README, and they are ones you could not have found yourself because you do those steps without noticing"}],"correct":true,"tempting":null}],"order":[0,1,2,3],"why":null},"prev":{"slug":"practising-failure","title":"Breaking it on purpose, on a Tuesday","minutes":8},"next":{"slug":"a-model-is-a-process-with-weights","title":"A prediction endpoint is a web service with a large secret","minutes":9}}}