The worst handover is a 40-page Google Doc that nobody opens after the kickoff call. The second worst is no documentation at all — just a Slack message saying "the code is self-explanatory."

When we delivered PayrollHQ to a client's internal team, the junior devs were productive on day three. Not because the code was simple — payroll logic never is — but because the docs answered the questions they'd actually ask.

1. Start with "how to run it in 5 minutes"

The first section of every README is a copy-paste setup guide. No prose. No architecture diagrams yet. Just:

git clone ...
cp .env.example .env
docker compose up -d
npm install && npm run dev
# App running at http://localhost:3000

If a new dev can't get the app running before lunch, everything else in the doc is wasted.

2. Document decisions, not just APIs

Junior devs don't need a list of every endpoint. They need to know why PAYE is calculated before NHIF deductions, or why we batch payslips at 2am EAT instead of on-demand.

Architecture docs explain what. Decision docs explain why. Your team needs both, but they read why first.

We keep a DECISIONS.md file — short entries, dated, with context and alternatives considered. No ADR ceremony. Just honest notes.

3. The "things that will bite you" section

Every project has landmines. We document them explicitly:

  • "The KRA API rate-limits after 100 requests/min — the retry logic is in tax/sync.ts"
  • "Don't delete rows from payroll_runs — soft-delete only, auditors check this table"
  • "Staging M-Pesa credentials are shared — don't run payout tests without checking the balance first"

This section saves more time than any diagram. It's the institutional memory that usually lives in one senior dev's head.

4. Video walkthroughs for complex flows

Written docs fail for multi-step UI flows. A 10-minute Loom showing "how to process a correction run" beats three pages of screenshots. We record these during development — not as an afterthought at handover.

Store links in the README. Update them when the flow changes. Delete outdated ones — stale videos are worse than none.

5. A living doc, not a tombstone

Handover isn't a single event. We include a "doc maintenance" clause in every project: when you change behaviour, update the README in the same PR. CI won't enforce doc freshness, but code review does.

We also schedule a 30-day check-in after handover. The questions that come up become new doc sections. The cycle repeats until the client team stops asking us.

What we ship in every handover package

README with 5-minute setup. DECISIONS.md with business context. Runbooks for deployment and incident response. Test instructions. And a single point of contact for the first month — because docs don't replace human backup, they reduce how often you need it.

Want a build your team can own, not depend on? That's how we deliver.