Articles · Documentation

2027-03-05 12 min EN / FR

The documentation you should demand at delivery

A project is delivered, the developer moves on, and a year later someone else must fix a bug or add a feature. They open the code and find no explanation of how it runs, where it is deployed, or why things were built that way. They spend days reverse engineering, and send you a bill.

Documentation is what makes software maintainable by someone other than its author. It is also the most commonly skipped deliverable, because it is invisible when the project works.

Why it matters

  • Continuity: if the developer is unavailable, someone else can continue
  • Cost: a new developer's first week is far cheaper with documentation
  • Freedom: you can change provider without being held hostage
  • Resilience: recovery after an incident is faster
  • Value: documented systems are worth more when the business is sold or audited

Documentation is not about volume. A short, accurate, current document beats a long, outdated one.

The essential set

1. README (the front door)

A short file at the root of each repository:

  • What the project does, in a few lines
  • How to run it locally, step by step
  • How to run the tests
  • Where to find other documentation
  • Who to contact

A test: a competent developer who has never seen the project should be able to run it in under an hour.

2. Architecture overview

One or two pages, with a diagram:

  • The main components (application, database, queue, external services)
  • How they communicate
  • Where each one runs
  • Key technical choices and the reasons for them

This is the document a new developer reads first to understand the whole.

3. Infrastructure and hosting

  • Providers and accounts used, with the owner of each (see the 30-minute account ownership audit)
  • Servers and services, with their purpose
  • Domains, DNS records and certificates
  • Network layout, firewall rules, access paths
  • Costs per month or year, and renewal dates

4. Deployment procedure

  • How code goes from the repository to production
  • Steps, commands and tools
  • How to roll back to the previous version
  • Database migration process
  • Who is allowed to deploy

If deployment depends on one person's laptop, document it and then fix it.

5. Configuration and secrets

  • List of environment variables and settings, with their purpose and example values (never real secrets)
  • Where the real secrets are stored and who can access them
  • How to rotate each key (see the offboarding checklist)
  • Third-party services and the credentials they need

6. Data

  • Database structure (a schema diagram and descriptions of important tables)
  • What personal data is stored, where and why (useful for your GDPR register, see GDPR and test environments)
  • Backups: what, how often, where, how to restore, and the date of the last successful test (see backups that actually restore)
  • Retention and deletion rules
  • How to export your data in a usable format

7. Integrations

For each connected system:

  • Purpose and direction of data flow
  • Authentication method and where credentials live
  • Schedule or triggers
  • Known limitations, rate limits and failure behaviour
  • Who to contact at the other end
  • How to check it is working (see syncing two systems: the five ways it breaks)

8. Business rules

The logic that encodes decisions your company made: pricing rules, discount thresholds, validation steps, approval flows, tax handling. Write them in plain language. This is often the most valuable documentation, because it is the hardest to recover from code.

9. Operations and runbook

  • What to monitor, and where
  • Alerts, and what each one means
  • Common problems and how to fix them
  • Routine tasks (renewals, updates, cleanups) and their schedule
  • Emergency procedures and contacts
  • How to turn off specific features safely (including any AI feature, see adding AI without handing over the keys)

10. Dependencies and licences

  • List of third-party libraries, frameworks and services
  • Licence type for each, and any restrictions
  • Paid licences, with the name they are registered under and renewal dates

11. User documentation

For the people who use the system:

  • A short guide for each role
  • Screenshots of the main tasks
  • Answers to frequent questions
  • Who to ask for help

12. Handover note

A final, dated summary: known issues, unfinished items, recommendations, and where everything is.

Need help defining what to demand?

We can turn this list into acceptance criteria for your next delivery, or review what you already received.

Describe your delivery Custom solutions

Quality criteria

Good documentation is:

  • Accurate: matches what actually exists
  • Current: updated when the system changes, with a date and version
  • Findable: in a known place, with an index
  • Written for the reader: a new developer or an administrator, not the author
  • Concrete: commands, examples, screenshots, not vague descriptions
  • Maintained: someone is responsible for updating it
  • Stored under your control: in a repository or document space you own

How to get it

Ask early. Put documentation in the quote and contract as a deliverable (see contract clauses to demand from any tech provider), with the list above or a subset, and an acceptance criterion.

Deliver it progressively. Documentation written at the end is rushed and incomplete. Ask for the README and architecture overview at the first milestone, and the rest as the system takes shape.

Test it. Ask someone who did not build the system to follow it:

  • Can they run the project locally from the README?
  • Can they deploy to a test environment using the procedure?
  • Can they restore a backup into a clean environment?

Every step where they get stuck is a gap to fix.

Keep it with the code where possible. Documentation stored in the repository, in text files, is versioned and travels with the project. A wiki is fine, but it must be in an account you own.

Include time for it. If you want documentation, it must be in the estimate. If it is an afterthought, it will not happen.

Documentation for small projects

You do not need twelve documents for a small website. A reasonable minimum:

  • A README (how to run and deploy)
  • A list of accounts, owners and renewal dates
  • Configuration variables and where secrets are stored
  • Backup and restore notes
  • A short user guide

One or two pages can be enough, as long as they are accurate.

Documentation and AI tools

AI tools can help draft documentation from code, and can summarise existing systems. The same rules apply as for code: a person must review it for accuracy, since generated documentation sounds confident even when it is wrong or out of date. Ask your provider whether and how they use such tools, and whether your code is sent to external services (see contract clauses).

Common mistakes

  • Treating documentation as optional or "for later"
  • Accepting a delivery with no README
  • Documentation that describes the plan, not what was built
  • Secrets written into documents or repositories
  • Documentation locked in the provider's tools or accounts
  • No owner after delivery, so it drifts out of date
  • Writing for experts only, with no user guide
  • Never testing it

Checklist

  • Documentation listed as a deliverable in the contract
  • README: run, test, deploy
  • Architecture overview with a diagram
  • Infrastructure, accounts and owners listed
  • Deployment and rollback procedure written
  • Configuration documented, secrets stored in our vault
  • Data structure, backups and restore procedure documented
  • Integrations documented
  • Business rules written in plain language
  • Runbook for operations and emergencies
  • Dependencies and licences listed
  • User guide for each role
  • Tested by someone who did not build it
  • Stored in an account we own, with someone responsible for updates

Related

From delivery to something you can maintain

If a project landed without usable docs, or you want acceptance criteria before the next go-live, write us.

Start a conversation All articles