What documentation are you entitled to require?
You're entitled to require documentation that lets a new developer take over the system without guessing. The minimum package is an architecture diagram, operations documentation, a README, and API documentation. Aim for living documentation in the code repo rather than separate binders nobody updates, and write the requirement into your Definition of Done and contract.
Documentation is the part of a development project everyone claims to want and nobody wants to pay for. Buyers fear either thick binders nobody reads, or a codebase so undocumented it becomes impossible to take over. The truth lies in between: you’re entitled to require documentation, but there’s a right amount. Too much is waste, too little is lock-in. Here’s how to find the right level and make sure it actually gets delivered.
The right level: what’s the measure?
The only meaningful measure of documentation is practical: can a new developer who’s never seen the system get into it without having to ask whoever built it? If an outsider can understand how the system fits together, how it runs, and how to build on it, the documentation is sufficient.
Anything beyond that risks becoming something nobody reads and nobody updates. Detailed documents describing every feature in words go stale the moment the code changes, and then they’re worse than nothing – they mislead. So aim for usefulness over volume. A short, accurate description beats a long, outdated one every time.
The point of documentation is independence. As long as only the person who wrote the code understands it, you’re locked in to that person or vendor. Documentation is what makes a system transferable.
The minimum package
Four types of documents cover most of the need. With these, you cover the most common situations: someone new taking over, troubleshooting or deploying the system, another system being connected.
| Document | What it should answer |
|---|---|
| Architecture diagram | How do the system's parts fit together, and why? |
| Operations documentation | How is the system run and deployed, and what do you do when something breaks? |
| README | How does a new developer get the development environment running? |
| API documentation | How do other systems call the interfaces, and what comes back? |
The architecture diagram is the most important and the most neglected. It doesn’t need to be beautiful – a simple picture showing the major parts and how they talk to each other goes a long way, and it saves the new developer days of guessing. The operations documentation is the one that hurts to be missing at three in the morning when something’s down and nobody remembers how to restart the system.
Living documentation in the repo
Where documentation lives decides whether it stays current. Separate documents in a folder alongside the code live their own life and quickly stop matching reality, since they’re updated on a different track than the code. Documentation that lives in the code repo, on the other hand, gets updated in the same motion as the code changes, and so stays alive.
A reasonable setup is to let the day-to-day stuff – how to build, run, and call the system – live close to the code in the repo, while an overview architecture picture can sit as its own document, reviewed periodically. The goal is for updating to be a natural part of the work, not a separate task that always gets forgotten. Whatever takes extra effort to keep current rarely stays current.
Write the requirement into Definition of Done and contract
Whatever isn’t required gets deprioritized as soon as time runs short, and time always runs short toward the end. So it’s not enough to wish for documentation – it has to be a delivery requirement.
Two places make it mandatory. In the Definition of Done, the team’s shared definition of what “done” means, write in that a feature isn’t finished until it’s documented. That way documentation gets built continuously instead of pushed to a final phase that rarely happens. In the contract, specify the minimum package as part of the delivery, so there’s a basis to stand on if it’s missing.
A scenario: the handover that didn’t hurt
A company switched development vendors after three years. Because the old team had documentation written into their Definition of Done from the start, there was a current architecture diagram, a working README, and operations documentation in the repo. The new team was up and running within a week or so.
Another company in the same situation, but without documentation requirements, instead had to pay the old vendor dearly for a long knowledge transfer – and guess their way through where memory failed. The difference wasn’t more skilled developers, but that one had required documentation from the start.
Want to set a reasonable documentation level for your project, enough but not excessive? We at Weapp are happy to help – and a technical review quickly shows how transferable an existing system actually is.
Frequently asked questions
How much documentation is enough?
Just enough that a new developer can get into the system without having to ask whoever built it. More than that often becomes binders nobody reads or updates. The measure is practical, not quantitative: if someone who's never seen the code can understand how it fits together, runs, and gets built on, that's enough. Aim for usefulness, not volume.
What belongs in a reasonable minimum package?
Four things cover most of it: an architecture diagram showing how the parts fit together, operations documentation describing how the system runs and gets deployed, a README that gets a new developer started, and API documentation for the interfaces other systems talk to. With these, you cover the most common needs at handover and when troubleshooting.
Is documentation in the code better than separate documents?
Usually, yes. Documentation that lives in the code repo gets updated in the same flow as the code and stays current, while separate documents quickly go stale. An architecture overview often still needs to live as its own document, but the day-to-day stuff – how to build, run, and call it – is best kept close to the code it describes.
How do we make sure documentation actually gets delivered?
By making it a delivery requirement, not a hope. Write into your Definition of Done that a feature isn't done until it's documented, and specify the minimum package in the contract. Documentation that isn't required almost always gets deprioritized when time runs short. Requirements and follow-up are what make the difference between intended and actual documentation.