A sales operations team uses a small tool every Monday to prepare a report for management. One colleague built it two years ago, on the side, and it has worked ever since. Then that colleague gives notice. Nobody else knows where the tool runs, how the data gets into it, or what to do when it stops.
This is a common situation, and it is rarely dramatic until the first failure. This article is for the head of technology or operations who is responsible for such tools. It describes a handover document of one page, the questions it must answer, and a simple test that shows whether it works. It is about ordinary business software, not about any particular product.
Why this is an ownership problem
The author of an internal tool usually holds three things in their head: the knowledge of how it works, the access to the places where it runs, and the informal right to decide what changes. When the author leaves, all three go at once. What remains is a tool that people depend on and that nobody is responsible for.
Our article on what to budget in years two to five of custom software shows that running and fixing a tool is a normal part of its cost. The handover is where that cost gets an owner. Without one, repairs wait until something breaks, and then they are done in a hurry by whoever is nearest.
Note that a handover is not the same as documentation of everything. A full manual is rarely written and even more rarely read. A page that people actually keep up to date is worth more.
The one-page handover
Put the page where the team already looks, for example next to the tool's source or in the team's shared space, and give it one name as its keeper. It has six parts.
- What the tool is for. Two sentences: who uses it, for what, and how often. If the tool disappeared tomorrow, who would notice first?
- Where it runs. The place where it is hosted, the address people use, and where its data is stored. Name the account or contract it sits under, not the password. Credentials belong in your password manager, and the page only says where to find them and who can grant access.
- Who fixes it. A named owner and a named deputy. The owner decides about changes and priorities; the deputy can act when the owner is away. A team alias is fine, as long as someone has the duty to read it.
- How to know it works. One check anyone can do in a minute, such as opening a page and seeing yesterday's date on the latest record. Add what usually goes wrong and the first thing to try.
- How to restore it. Where backups are, how often they are taken, and the steps to bring the tool back from one. Include the date when someone last tried it.
- What it depends on. Other systems it reads from or writes to, files it expects, scheduled jobs, and licences of other products. This is the part authors forget most often, because to them it is obvious.
Add two more lines at the bottom: where the source is kept, and the date of the last review. That is all.
Write it before the farewell
The best moment to write the page is while the author is still present and still motivated to help. A good order is this.
- Ask the author to fill in the six parts as well as they can in an hour. Do not ask for polish.
- Ask the new owner to read it and mark every sentence they do not understand.
- Sit down together for thirty minutes and close the gaps. These are usually in dependencies and in access.
- Move access from the author's personal accounts to accounts the company owns. This takes longer than the writing, so start early.
If the author has already left, the same method works with more guessing. Start from what the tool does, trace where it runs, and write down what you find. Mark everything uncertain as uncertain on the page; an honest gap is more useful than a confident mistake.
Test the page with a newcomer
A handover that has not been tested only looks complete. The test is short and needs one person who has never worked with the tool, such as a new colleague or someone from another team.
Give them the page and nothing else, and ask three things.
- Find the tool and tell me whether it is working right now.
- Tell me who you would call if it were not, and what you would tell them.
- Describe, step by step, how the tool would be restored from a backup. You do not need to do it, only to explain what you would do and where you would find each thing.
Write down every place where the newcomer hesitated or asked a question. Each one is a missing or unclear sentence on the page. Fix them and, if you can, repeat the test a month later with someone else.
For a tool that matters, go one step further once a year and actually restore it into a test location. This is the only way to know that the backup is usable.
Who decides about changes
Ownership is not only about repairs. People will keep asking for small changes, and the owner needs a simple rule. A workable one is to separate three kinds of request. Fixing something that is broken goes to the owner directly. A small change that fits in an agreed amount of time per month, such as a few hours, is the owner's decision. Anything larger goes to the person who pays for the tool, together with an estimate and a reason.
Write the rule on the page in one line. It prevents both extremes: a tool that nobody dares to touch and a tool that grows without anyone deciding to grow it. If requests keep piling up, that is a sign the tool may deserve a proper plan, as discussed in our article on moving from a spreadsheet to a small internal tool.
When to review
Review the page twice a year, and also whenever one of these happens: the tool moves to a different host, a system it depends on changes, the owner or the deputy changes role, or a failure shows that the page was wrong. The review takes ten minutes: read each part, correct what has changed, and update the date.
If you find tools that have no page at all, do not try to fix everything at once. List them, rank them by how much work stops if they stop, and start with the top one. The cost of ignoring them is the subject of our article on the hidden cost of technical debt.
What to do this week
On Monday, list the internal tools your teams use and mark those whose author has left or is about to. On Tuesday, pick the most important one and name an owner and a deputy. On Wednesday, ask the owner to draft the six parts, with the author's help if possible. On Thursday, run the newcomer test and note the gaps. On Friday, fix the page, set the next review date, and move any access that is still tied to a personal account.
Sources
- Our related articles linked above.
- The handover outline is a general method and does not describe a particular company, tool or supplier.