The Script Nobody Can Read: Undocumented Automation as Institutional Risk
Photo by Photo by M. Cooper on Unsplash on Unsplash
Every organization has one: a script that runs nightly, nobody knows exactly what it does, and the only person who understood it left eighteen months ago. It still works, so it stays. When it breaks — and it will — the response is not repair but archaeology, followed usually by an expensive rewrite.
We have language for shadow IT: unsanctioned systems that carry risk precisely because they operate outside visibility. An undocumented, business-critical script is functionally identical. It encodes operational knowledge that exists nowhere else — in one person's head, or worse, in a former employee's head. That is institutional risk, and it deserves to be named as such in risk registers, not shrugged off in hallway conversation.
Why Engineers Skip the README
The excuses are honest, at least. Documentation is invisible work: it produces no working feature, no demo, no ticket closure. Managers reward shipped scripts, not shipped explanations. And there is a subtler psychological factor — the author finds the script self-evident, because they built the context. Documentation feels redundant to the one person who will never need it.
The result is a knowledge monoculture. The script works until the author's last day, and then it becomes a black box with a production schedule.
What 'Good Enough' Actually Looks Like
Perfection is the enemy here. Documentation that takes an hour per script will not happen; documentation that takes ten minutes will. Three practices cover most of the value.
Self-describing --help output. If the script cannot explain its own usage, arguments, and prerequisites, it is incomplete. Treat a help block as part of the definition of done:
Usage: sync-inventory.sh [--dry-run] [--env prod|staging]
Pulls inventory deltas from the ERP API and updates the
warehouse DB. Requires ERP_TOKEN in the environment.
Inline assertions. Comments that explain why — "the API rate-limits at 60/min, hence the sleep" — outlive the author. Better still, encode assumptions as executable checks: verify the token exists, verify the endpoint responds, fail with a human-readable message. A script that explains its own failure modes documents itself at runtime.
A runbook entry, not a novel. Three questions suffice: What does this do? What does it depend on? What do I do when it fails? A one-page runbook linked from the script's repository header answers all three.
Making Documentation a Byproduct
The structural fix is to stop treating documentation as a separate activity. Enforce --help in code review. Generate usage docs automatically from argument parsers — [argparse](https://en.wikipedia.org/wiki/Command-line_argument_parsing), PowerShell's comment-based help, clap — so the docs cannot drift from the code. Add a documentation checklist to the definition of done for automation work, the same way tests are.
Some teams go further and treat a missing runbook as a production incident finding after any breakage. That may sound bureaucratic until you price out the alternative: the rewrite of a load-bearing script that three people were afraid to touch.
The best time to document a script is when you write it. The second-best time is before the person who wrote it cleans out their desk.