Software is usually declared done when it passes acceptance testing. That is a reasonable commercial milestone and a poor engineering one, because it measures the system on the day the people who built it are still in the room.
The more useful test is a handover test: could a competent engineer who has never spoken to us make a safe change to this system using only what is written down? Not a heroic change. A routine one, on a Tuesday, without a phone call.
Most systems fail that test, and they fail it in predictable places. Environment setup that lives in someone's shell history. A deployment step that is technically documented but has an undocumented ordering requirement. Business rules that are correct in the code and unexplained anywhere, so the next engineer cannot tell an intentional edge case from a bug.
Treating handover as a requirement rather than a phase changes what gets built. Setup becomes a script because a script is the only documentation that cannot drift. Architectural decisions get a short written record of what was chosen and what was rejected, which is what a new engineer actually needs. Tests get written around business rules specifically so the rule survives someone not understanding it.
None of this is expensive at the time. All of it is expensive to retrofit, which is why it almost never gets retrofitted, which is why so many organisations are afraid of systems they own.
We hold ourselves to it for a selfish reason too: the alternative to a system that can be handed over is a client who is dependent on us. That is a worse business than a client who stays because the work is good.
- architecture
- documentation
- handover
