What documentation should I require when a software project is delivered?
Enough that a developer who has never seen the system can run it locally, deploy a trivial change, and diagnose the most common failure — without calling the person who built it. That means a repository readme, a configuration inventory, a data model, an integration list with credential owners, a deploy procedure, a runbook for known failures, and an honest list of shortcuts taken.
The standard to hold it to
Documentation quality is easy to argue about and easy to test. The test is a task: give the package to a competent developer who was not involved, and ask them to stand the system up and change something small. Whatever they have to ask about is what is missing.
Do this before final payment, not after. It converts a subjective conversation into a checklist.
The seven artifacts that matter
- Readme. How to get the code running on a new machine, with prerequisites and versions.
- Configuration inventory. Every environment variable and setting, what it does, and where the production value is stored.
- Data model. The main entities, how they relate, and any field whose meaning is not obvious from its name.
- Integration list. Each external system, what is read and written, which account owns the credential, expiration dates, and where the vendor's deprecation notices arrive.
- Deploy procedure. The exact steps to release, and the exact steps to roll back.
- Runbook. The three or four failures most likely to occur, how they present, and what to do about each.
- Known debt. The shortcuts taken and why. This is the item most often omitted and the most valuable to the next person.
Documentation that stays true
Long documents drift out of date within a quarter and then actively mislead. Prefer short documents plus things that cannot lie: scripts that set up an environment, configuration checked into the repository, and a deploy that is a command rather than a memorized sequence.
A one-page readme next to an automated setup is worth more than a fifty-page manual describing steps nobody performs anymore.
Include the operational knowledge, not just the code
Much of what makes a system supportable is not in the source at all: which scheduled jobs exist and where they run, which alerts go to whom, what normal load looks like, and what a healthy day of data volume looks like so an abnormal one is recognizable.
Write that down alongside the technical docs. It is the difference between inheriting software and inheriting a working system, and it is why we treat handoff artifacts as a deliverable in every build and in ongoing integration work rather than as a courtesy at the end.
Topics: documentation · handoff · runbook · continuity
Have a version of this question about your own business?
The useful answer usually depends on which systems you run and how they're connected. That's a conversation, not a blog post.