MODULE 11 / 18 · PART 4 · SHIP & SUSTAIN
Documentation & Communication
Write for the reader who will make the decision or fix the system without you.
THE SHORT ANSWER
What this module changes.
A document without an audience is a document nobody reads. Name the reader, the decision, and the action the document must produce.
Documentation prompts should specify the audience and the decision the document is meant to drive. A document with no audience is a document nobody reads.
Handovers to NGOs, government agencies, agencies and new hires often fail on missing context rather than missing code. A README, an ADR and a runbook are part of the deliverable, not optional extras.
THE MODULE PROMPT LIBRARY
20 prompts for documentation.
Copy any prompt, replace the [bracketed] slots with your own project context, and attach the files the agent needs. Use “Copy all prompts” when you want the full module in one place.
20 copy-ready prompts. Bracket text is a slot for your own context — replace it before you send the prompt.
Write an ADR for this decision: context, options considered, decision, consequences, and status. Keep it under one page.
Why it worksThe ADR format captures the why, which is what future engineers need.
Explain [system] to a new engineer in their first week: what it does, how it fits, and what to read next.
Why it worksOnboarding docs have a clear audience and a clear success test.
Write the README for [service]: what it does, how to run it locally, how to deploy it, and who owns it.
Why it worksThe four questions every engineer asks about an unfamiliar service.
Document this API for a consumer who has never seen our system: endpoints, auth, errors, rate limits, and examples.
Why it worksConsumer-first API docs reduce support load and integration bugs.
Write the runbook for [alert]: what it means, how to diagnose it, and how to fix it.
Why it worksRunbooks are the highest-value docs in an on-call rotation.
Explain this code to a future maintainer: the intent, the constraints, and the parts that look wrong but are not.
Why it worksThe "looks wrong but is not" section prevents well-meaning regressions.
Write the design doc for [feature] with the problem, the constraints, the options, the recommendation, and the open questions.
Why it worksStructured design docs get decisions made in one meeting.
Summarize this incident for a non-technical audience: what happened, the impact, and what we are doing about it.
Why it worksDifferent audience, different document; this produces the right one.
Write the migration guide for [change] aimed at downstream teams: what breaks, what to do, and the deadline.
Why it worksMigrations fail on communication, not on code.
Turn this code comment into proper documentation: [comment]. Expand the why and remove the what.
Why it worksComments explain the moment; docs explain the system.
Write the release notes for [version] for two audiences: engineers and users.
Why it worksOne release, two readers, two documents.
Document the failure modes of [service] and the expected behavior for each, for the on-call engineer.
Why it worksPre-decided responses shorten incidents dramatically.
Write the one-pager that gets [proposal] approved: problem, cost of inaction, proposal, cost, and the ask.
Why it worksDecision documents need an explicit ask or they stall.
Explain the trade-offs in [decision] to a product manager in terms of user impact and delivery time.
Why it worksTranslates engineering trade-offs into the language of the decision maker.
Write the glossary for [domain] so that code, docs, and conversations use the same words.
Why it worksA shared vocabulary removes a whole class of misunderstanding.
Document the local development setup for [project] so a new engineer is productive on day one.
Why it worksSetup friction is the first impression of your codebase.
Write the architecture overview for [system] at three levels of detail: executive, engineer, and deep dive.
Why it worksOne document, three audiences, no repetition.
Turn this Slack thread into a durable document: [thread]. Extract the decision and the reasoning.
Why it worksRescues decisions from the place where they go to die.
Write the deprecation notice for [feature]: what is going away, when, what replaces it, and how to migrate.
Why it worksDeprecations without a migration path get ignored.
Review this document for the reader's questions: what would they ask that we have not answered?
Why it worksTests the document against its actual purpose.
PRACTICE · 20–30 MINUTES
Try it on a project you actually own.
Write the README for a service you own using prompt 3. Ask a colleague to run it on a clean machine and note every question they ask.
- Pick one prompt from this module that matches a real task.
- Replace every bracketed slot with context from the feature you are working on now.
- Attach only the files the agent needs. Keep secrets, credentials and personal data out of the chat.
- Ask for the artifact — a spec, diff, test, runbook or decision note — and the evidence that it works.
- Record what changed and what remains unverified in the repository.
Want the same prompts across every module? Search the full prompt library or return to the course overview.