Direct answer
Documents that only the builder can read do not count. When you buy custom software you should receive a small, specific set of documents that allow a competent stranger to understand how the system is put together, run it, fix routine problems and change it: an architecture overview, a list of environments and configuration, a data dictionary, runbooks for routine tasks, user guides, a record of decisions and notes on any APIs.
Documentation should be short, accurate and findable. A large document nobody keeps up to date is less useful than a single accurate page. Ask for these items in the written scope before work begins, since documentation requested at the end tends to be written in a hurry. This page is about what to receive; the operational side of transfer is in the software handover checklist, and ownership in who owns the code and accounts after a custom build.
Architecture overview
An architecture overview explains what the main parts of the system are and how they fit together: the user-facing application, the server side, the database, file storage, background jobs and the external services involved. One diagram and a page of text is usually enough.
The test of a good overview is whether a new developer could use it to decide where a given change belongs. It should also name the technologies used and why, at least in brief, and point to where the code for each part lives.
Environments and configuration list
List every environment the software runs in, such as production, staging and local development, and for each one say where it runs, who can reach it and how a change is deployed to it. Alongside that, keep a configuration list: the settings the application reads, what each one does, where it is set and which ones are secret.
The list should contain the names of the settings and where to find them, never the secret values themselves. Secrets belong in a password manager or the hosting platform's secret store, and the list should say which. Together, these documents answer the question 'if this stopped working tomorrow, what do I need to look at?'
Data dictionary
A data dictionary describes the information the system stores: the main tables or collections, what each field means, which are required, and how records relate to each other. It is especially valuable where field names are technical, or where the business meaning of a value is not obvious from its name, such as what each status means.
This is the document you will need if you ever want to report on the data, move it to another system or hand it to an analyst. Ask for it in a form people can read, not only as a generated schema file.
Runbooks
A runbook is a step-by-step guide for a routine or urgent task, written so that someone unfamiliar can follow it. Ask for runbooks covering the things that will genuinely happen.
- Deploying a change and rolling it back
- Restarting the application and checking it is healthy
- Adding, disabling and resetting users
- Restoring from a backup
- Renewing certificates, domains and credentials that expire
- Where to look first when something breaks
User guides
User guides are for the people who use the software each day, not for developers. They should be organised by task, in the words your team uses, with screenshots where they help. Separate guides for different roles are often clearer than one large manual.
Consider whether an administrator guide is needed as well: how to manage users, permissions, lists of options and other settings that do not require a developer. If a task can be done by your own staff, it should be documented so it does not become a support request.
Decision log
A decision log records the important choices made during the build and the reasons: why one approach was chosen over another, what was deliberately left out, what trade-offs were accepted. It is the cheapest form of documentation to keep and one of the most useful, since it stops later teams undoing something for a good reason they cannot see.
Entries can be a few lines each: the date, the decision, the alternatives considered and the reason. Include known limitations and unfinished items, honestly labelled.
API notes
If the software exposes an API, or calls other systems' APIs, ask for notes on each: what it is used for, how it authenticates, what the main requests and responses look like, and what happens on failure. For integrations, note which system is the source of truth for which data, and where credentials are stored. The related page on API credentials and service account setup covers the access side.
If your software is used by other systems or partners, an API description that outsiders can follow is essential, and it should be kept in step with the code.
The stranger test
Before accepting the documentation, apply the stranger test: give it to someone who was not involved in the project and ask them to do three things using only the documents: explain how the system fits together, deploy a change to a non-production environment and perform one of the runbook tasks. Where they get stuck is where the documentation is missing or wrong.
Do this while the original team is still available to fix the gaps. Then agree how the documents will be kept up to date after changes, and who owns that job.
Where LATYNEX fits
LATYNEX builds custom web applications remotely, in English, agreeing one scope and one price in writing before work starts. Listing the documents you expect in that scope keeps them from being assumed. Start at web application development if you are planning a build.
Questions
How long should the documentation be?+
As short as it can be while passing the stranger test. Accuracy and findability matter more than volume.
Should documentation live in the code repository?+
Technical documents usually work well there, since they can change alongside the code. User guides may suit a shared space your team already uses. Whatever you choose, make sure you own and can access it.
Who keeps documentation up to date?+
Decide it explicitly. Whoever makes a change should update the affected document as part of the change, and someone on your side should own the set.
Is a recorded walkthrough a substitute?+
No, though it is a good supplement. Recordings are hard to search and go out of date quickly; written documents for the key items are still needed.
What if the builder says documentation costs extra?+
Ask for it to be listed in the written scope so what you are getting is clear. It is much easier to agree before the build than to negotiate at the end.