Every so often a business finds out that something important runs on a script nobody else has read. It might be the overnight job that turns orders into invoices, the spreadsheet with the macros that finance can’t close the month without, or a small internal app on a machine under someone’s desk. It works, so nobody has looked at it for two years, and then the person who built it goes on leave, changes role or leaves the company.
None of that means the tool was a mistake. Bespoke tools are often the sensible answer, and plenty of them run quietly for years. The risk is that all the knowledge about them sits in one head. The rest of this is about moving it onto paper, into version control and into somebody else’s hands before you need it.
What we mean by maintainable
For a tool this size we’d keep the definition plain. Maintainable means a capable person who has never seen it can find it, understand what it does, change it safely and put it back if it breaks, using only what’s been written down and stored. That isn’t a formal standard, and it’s a lower bar than “well engineered”, which is why it’s within reach for a script or a spreadsheet process.
We’re a technical consultancy and not a software agency, so this isn’t a pitch to build you something. It’s the discipline we’d look for if we were asked to review a tool someone else had made, and it applies whether the tool is a hundred lines or a few thousand. Keeping such a tool cared for over time can sit within continuing support, arranged individually, with the scope agreed first.
The readme that answers the awkward questions
Most documentation fails because it describes what the tool is for and skips what a stranger needs on a bad day. The useful version is short and sits next to the code, and it says what the tool does in a couple of sentences, what it reads from and writes to, when and how it runs and what normal looks like. It also says what to do when it fails, in the order you’d try things.
Where it runs matters as much as what it does. Name the machine or service, who can log on to it and how the job is scheduled, because a task scheduled under one person’s own login stops the day that account is disabled. If it only runs from a laptop, say so, and treat that as the first thing to fix.
Who holds the keys
Almost every tool holds credentials of some kind: a service account, an API key, a connection string, a certificate. The readme should list each one by name and say where it’s stored, who owns it, what the tool uses it for, what breaks if it changes and whether it expires. It should never contain the secret itself.
Keep secrets in a place the organisation controls, such as a password manager or a secrets store, and not in a file next to the code or in the author’s own account. And make sure the account the tool signs in with belongs to the business, with a named owner who isn’t the author. Where a credential has an expiry date, put that date in a shared calendar, because an expired key at two in the morning is a miserable way to rediscover a tool.
What it stands on
A tool depends on things its author installed once and forgot, such as a language runtime, a handful of libraries, a database driver or a macro-enabled workbook that needs a particular version of Office. Record each one with the version in use. For the runtime and any platform it needs, look up the vendor’s published support dates on the vendor’s own lifecycle page and write the end-of-support date in the readme, rather than trusting memory.
That date does two jobs. It tells you when the tool will start running on software nobody is patching, and it gives you a reason to put maintenance in the diary before it becomes an emergency. If other people or systems rely on the tool’s behaviour and it carries version numbers, the Semantic Versioning 2.0.0 specification offers a tidy convention: increase the major number for incompatible changes, the minor number when you add functionality in a backward compatible way and the patch number for backward compatible bug fixes. For a small internal tool, even a dated change log kept beside the code serves the same purpose.
A few tests, and a way to see it fail
Nobody is asking for full test coverage on a script. Pick the few places where a wrong answer costs money or trust, which is usually the calculation, the rule that decides who gets what and the input that has broken it before. Write those down as checks that can be run in a minute against a small set of made-up data. Add a dry-run option that shows what the tool would do without doing it, if the work involved can’t easily be undone.
A tool that fails silently is worse than one that falls over loudly, so have it record when it started, what it processed, how many records it handled and a plain-language reason if it stopped. Keep the log somewhere that survives a restart, leave credentials and personal data out of it, and arrange for someone to be told when the expected run doesn’t happen. Alerting on a missing success message is often the quicker way to spot a job that has stopped.
Copies of the code and the configuration
If the only copy of the tool is on the machine it runs on, you have a single point of failure with a short fuse. Keep the code in version control that the business owns, and keep the configuration alongside it, with real secrets replaced by placeholders. A spreadsheet-driven process needs the same treatment: a dated copy of the workbook, with its macros, stored somewhere that’s backed up.
To test the documentation, ask someone who isn’t the author to rebuild the tool on a clean machine, using only the readme. Every place they get stuck is something missing from the documentation, and it’s far cheaper to find out on a quiet afternoon.
A handover checklist, and the day the author leaves
Picture, as an invented example, a company where one employee wrote a nightly script that collects supplier price lists and updates a pricing spreadsheet, and then hands in their notice. For that script, the list below would mean the supplier logins are owned by the business and written down, and the scheduled job no longer runs under the leaver’s own account. The list works at any time, not only when someone resigns.
- The readme is current and someone else has followed it end to end.
- Every credential is listed, owned by the business and has a known owner and expiry date.
- The code and configuration are in version control the business controls.
- The runtime and dependencies are recorded, along with the vendor’s end-of-support date for each.
- The checks run, the logs are readable and someone is told when a run is missed.
- A named person is responsible for the tool and has a deputy.
When the author is leaving, ask them to run it with their successor watching, then have the successor run it alone while the author is still reachable. Move any account that’s tied to the author’s own login (in the invented example, the price-list script’s scheduled job and its supplier logins), then review who has access to the tool and to the machine it runs on. Decide at that point whether the tool is worth keeping, replacing or retiring, because a handover is the cheapest moment to ask.
If the author has already gone, the same order applies but you start from the machine and the scheduler and read your way back, which is slower and is another reason to do the work earlier.
If something in your business depends on one person’s memory, you’re welcome to tell us what it does and where it runs and we’ll talk through what a sensible next step looks like.