Software Documentation Businesses Should Require

Software documentation is the written record that lets someone other than the original developers run, change and fix your system. Businesses should require an architecture overview, setup and deployment steps, a configuration list, API and data model documentation, user guides and incident runbooks. Put these in the contract as deliverables, keep them in the code repository and test them by asking a stranger to deploy the system.

Key takeaways

• Undocumented software ties your business to the people who wrote it, which raises cost, risk and switching difficulty.
• Ask for a defined set of documents, not just "documentation", and say in the contract what format and level of detail you expect.
• Documentation should live in the repository next to the code and be updated as part of every change.
• A handover checklist at the end of a project should cover code access, credentials in your own accounts, deployment steps and recovery.
• The best test for a non-technical owner is simple: can someone who has never seen the system deploy it from the documents alone?
• Docs written at the very end of a project are usually thin, so require them throughout.

Why is undocumented software a business risk?

Software that only its authors understand creates three practical problems.

1. Key-person dependency. If the one developer who knows how things fit together leaves, falls ill or simply becomes unavailable, nobody can safely change the system. You are left reading code like archaeology.
2. Onboarding cost. Every new developer or agency has to spend paid hours reverse engineering what was already known. Good documents shorten this dramatically.
3. Vendor lock-in. A supplier who holds all the knowledge holds the leverage. Even if you legally own the code, you cannot realistically move without documentation. Our guide to who owns the code in custom software covers the legal side, and documentation is what makes ownership usable.

What types of documentation should you ask for?

Not every project needs every item at the same depth. For a business application, this is a sensible core set.

Architecture overview

A short description of the main parts of the system, how they talk to each other and where they run. A page or two plus a diagram is usually enough. For background on the typical parts, see web application architecture basics.

Setup and deployment runbook

Step-by-step instructions to run the system locally and to deploy it to each environment, including the order of steps, build commands, database changes and how to roll back.

Environment and configuration list

Every setting the system needs, what it does, and which environments use it. The names of secrets belong here, but never the secret values.

API documentation

For each endpoint: purpose, inputs, outputs, errors, authentication and any limits. Ideally this is generated from the code or a specification file so it cannot drift far.

Data model

The main entities, how they relate, what the important fields mean and any rules that are enforced. This is essential when you later need reporting, migration or integration.

User and admin guides

Plain-language instructions for the people who use the system daily, including how to carry out administrator tasks such as adding users, changing content or handling exceptions.

Decision records

Short notes that capture why an important technical choice was made, what alternatives were considered and what trade-offs were accepted.

Incident runbooks

What to check and who to call when something fails: the site is down, payments are failing, emails are not arriving. Our guide to an incident response plan shows how these fit together.

Test plan

What is tested, how to run the tests and what a successful release looks like. This helps whoever maintains the system keep quality steady.

What should you write into the contract?

If it is not in the contract or statement of work, it tends not to appear. Make it specific.

• Deliverables: list each document by name, not just "documentation will be provided".
• Format and location: for example Markdown files in the repository, plus exported copies in a shared folder you control.
• Level of detail: a new developer with general skills in the stack should be able to follow it without calling the original team.
• Update obligations: documents must be updated whenever the related change is released, and a milestone payment can depend on it.
• Acceptance: you may test the documentation, as described below, before final acceptance.

Our guide on how to choose a web development agency includes questions to ask suppliers about their documentation habits before you sign.

What should a repository README contain at minimum?

The README is the front door for every developer. At minimum it should explain:

1. What the system does and who it is for, in a few sentences.
2. The technology used, and the prerequisites to run it.
3. How to set it up locally, from a fresh machine to a working app.
4. How to run the tests.
5. How to deploy, or a link to the runbook.
6. Where to find configuration, other documents and the architecture diagram.

If a developer cannot get to a running app from the README alone, it needs more work.

Which diagrams actually matter?

Pictures help, but only a few earn their place.

• System context diagram: your system in the middle, with users and external services around it.
• Component or architecture diagram: the main building blocks and the direction of data between them.
• Data model diagram: entities and relationships.
• Deployment diagram: servers, services, networks and where each piece runs.

Keep diagrams editable in a text-based or open format so they can be updated, not just exported as images that nobody can change.

How do you keep documentation current?

Documentation rots when it lives apart from the work. These habits keep it alive.

• Docs in the repository. They are versioned with the code, so a change and its explanation travel together.
• Part of the definition of done. A feature is not finished until the relevant documentation is updated, and reviewers check it.
• Date and owner. Mark when each page was last reviewed and by whom.
• Review periodically. Part of ongoing support, as described in software maintenance and support after launch, should include a documentation check.

What belongs in a handover checklist at project end?

Use a checklist so that nothing is left to goodwill.

1. Code access: repository ownership in your organisation's account, with the supplier's access removed or reduced as agreed.
2. Accounts and credentials: hosting, domain, cloud, email, analytics, payment and monitoring accounts registered to your business, not a developer's personal account.
3. Secrets: stored in a password manager or secrets vault you control, rotated after handover.
4. Deployment: the deployment runbook proven by a supervised deployment.
5. Backups and recovery: where backups are, how to restore and when it was last tested.
6. Documents: the full agreed set, delivered and checked.
7. Third-party services: a list with owners, renewal dates and what each is used for.
8. Walkthrough: a recorded or live session explaining the system to your team.

How can a non-technical owner test the documentation?

You do not have to read code to check quality. Try these tests.

• The stranger test: ask an independent developer, or a different team, to deploy the system to a clean environment using only the documents. Every question they ask reveals a gap.
• The restore test: ask someone to restore from a backup following the runbook.

What tools help with documentation?

Categories matter more than brands. Most teams combine Markdown files in the repository for README, runbooks and decision records, a wiki or knowledge base for user guides, generators that produce API references from a specification, editable diagramming tools and recorded walkthroughs as a supplement to written steps.

Common mistakes to avoid

• Leaving all documentation to the last week of the project.
• Accepting a long, vague document that never mentions how to deploy.
• Outdated screenshots and steps that no longer match the interface.
• Keeping documents, or secrets, on a supplier's private drive.
• Documenting what the system does but not why decisions were made.

A worked example

Imagine a retailer whose ordering system was built by a freelancer who has taken a full-time job. The new agency spends weeks working out how orders flow, where the server is and which scheduled jobs run. Had the contract required a deployment runbook, configuration list and data model, work could have started in days. The retailer now asks for a documented handover and tests it with a third-party deployment before the final payment.

FAQ

What documentation should I require from a software developer?

At minimum, ask for an architecture overview, setup and deployment instructions, a list of configuration settings, API and data model documentation, user and admin guides, and incident runbooks. Specify each as a named deliverable in the contract. Add decision records and a test plan for larger systems.

Who should own the documentation for custom software?

Your business should own it, together with the code. State this in the contract and keep copies in repositories and shared storage that your organisation controls, not on a supplier's private systems.

How do I know if software documentation is good enough?

Run the stranger test: ask an independent developer to deploy and run the system using only the documents. If they can do it with few questions, the documentation is useful. If they get stuck, the gaps they report tell you what to fix before final acceptance.

How often should software documentation be updated?

Update it whenever the related behaviour changes, as part of the same piece of work that changes the code. Review the whole set periodically, for example during maintenance, to catch pages that have drifted.

Related reading

• Who Owns the Code? IP and Licensing in Custom Software
• Software Maintenance and Support After Launch: What to Plan
• How to Choose a Web Development Agency and Spot Red Flags

Next steps

Pick one live system you depend on and run the stranger test on it, or ask your current supplier for the handover checklist above. Where gaps appear, add them to the next maintenance cycle or contract. If you would like help creating or auditing documentation for an existing system, contact us and we can review what you have.