Custom software comes with no manual on the internet. There’s no forum where another user already asked your question, no supplier with a knowledge base about your system. Everything worth knowing about it sits in the code and in the heads of the people who built it. Documentation is the only place that knowledge survives once those people move on.
That makes documentation for custom software far more than an administrative afterthought: it’s part of the product. It determines whether your system can still be adapted in five years’ time, how quickly a new team member gets up to speed, and above all whether you, as the owner, get to choose who works on it next.
Documentation determines how dependent you are
With off-the-shelf software you can always fall back on the supplier: manuals, a support desk, a community of users. With custom software, that external source doesn’t exist. If the knowledge disappears, reverse engineering is the only way back: reconstructing what the system does from the code alone. That’s possible, but it’s slow, costly and prone to error.
An undocumented system ties you, in practice, to the party that built it, no matter how little reason remains to keep working together. Good documentation is therefore a form of ownership, just like holding your own source code. For how to arrange that ownership contractually, read our article on preventing vendor lock-in.
Four layers, each with its own reader
Good documentation isn’t one thick document trying to describe everything. It’s a set of thin layers, each serving its own reader.
- User documentation: how end users and administrators carry out their day-to-day tasks in the system.
- Technical documentation: the architecture, the data structure and how you run and deploy the system, for developers.
- API documentation: how other systems connect, what data is available and in what form.
- Decision documentation: why choices were made the way they were, from business rules to the reasoning behind them.
That last layer is the one most often skipped, and the one most sorely missed. What a system does can, at a pinch, be read from the code. Why it does it that way cannot.
How we keep clients independent of us
At eenvoud, we treat documentation as part of the system itself. It lives in the same repository as the source code, so a change to the software and its accompanying description are reviewed together and delivered together. Outdated documentation then stands out just as clearly as a bug in the code.
The standard we hold ourselves to is transferability: a development team that has never seen the system before should be able to carry on independently with just the source code and the documentation. That’s why every delivery includes a description of how to run the system locally, how a release works, where the integrations sit and which choices were made deliberately. Not because we expect clients to leave, but because software only the original developer can maintain isn’t a good product. We’ve seen enough systems outlast the team that built them to know that transferability becomes necessary sooner or later.
Keeping it current is the real work
Outdated documentation is worse than no documentation: it creates trust it doesn’t deliver on. It only stays current if updating it is part of the development process itself. A change isn’t finished until the description is accurate again, and whatever can be generated automatically from the code, an API overview, say, is better generated than maintained by hand.
So when you ask your software partner about documentation, don’t just ask whether it happens. Ask when: during the work, or afterwards. That one answer predicts how useful the documentation will still be in a few years’ time.
Is there custom software running in your organisation whose documentation is thin or out of date? Don’t start with everything at once. Start with the spots where the most knowledge is at stake: the functions used every day and the choices nobody can explain any more. Within ongoing development and maintenance we do this regularly for systems others built: understand and record first, only then change anything.