Documentation and presentation
🏠The everyday picture
A building's handover pack: the plans, the wiring diagram, where the stopcocks are, the maintenance schedule, and who to call. The next owner can look after it without the builder.
📘What it really is
- Schema documentation:
- the ER diagram (kept current);
schema.md: each table's purpose, columns that need explaining, rules, delete behaviour, deliberate copies;-
migration history in Git.
-
Operations documentation (
admin.md): roles, backup schedule, restore steps with timing, monitoring, maintenance, personal-data handling. -
README: how to set up a local database, run migrations and seeds, run tests, and connect the app.
- Presentation: show
- the ER diagram and one design decision you'd defend (a normalisation choice, a delete rule);
- a report answering a business question;
- a transaction failing safely;
- a permission or RLS check refusing access;
-
the restore drill.
-
Be ready to explain and change any part yourself, as at every level.
🖱️Try it
Complete the documentation and rehearse the five-part presentation, recording it. Ask someone (or an AI acting as a new developer) to set up the project from your README alone, and fix whatever they get stuck on.
✅Quick check
Who is database documentation really for?
Show the answer
Anyone who must understand, run or recover the system later, including you, months from now.
Why test your README with someone else?
Show the answer
You can't see the steps you've forgotten to write down; a newcomer finds them immediately.