Professional Facepalms: A Six-Part Series
Because if you can’t laugh at your own career mistakes, someone else will.
Part #6 - Pass It On Before You Move On
Our eternal hate-hate relationship with documentation.
In this, the final installment of Professional Facepalms: A Six-Part Series, I talk about the biggest and potentially most dangerous misstep — not prioritizing the documentation of your systems and procedures to the point of kneecapping the knowledge transfer process.
Or, as it’s more commonly known in legacy IT shops, “Uh-oh, Grace is retiring next week.”
Whether you’re in IT, HR, finance, manufacturing, or any role where systems outlive their creators, the danger is there. For me, working in an aging IT shop meant that we seemed to be one retirement away from disaster. Writing things down can often be the difference between continuity and chaos.
Documentation Before Retirement: A Write of Passage
For most of my career, we treated documentation as an afterthought. We all agreed it was important, and we all knew it would make our lives easier in the long run. But we never actually did it. We were a small team, perpetually understaffed, and always sprinting toward the next deadline. Writing things down felt like a luxury — something you did after the real work was done, which, of course, meant never.
At the end of the day, it became just another good intention that we used to pave our own road to IT hell.
Okay, okay…our own sixteen-lane superhighway to IT hell.
Then the modernization project came into focus and was kicked off amid tremendous excitement for everyone outside of the Digital Division and unmitigated terror for the rest of us. Suddenly, the decades-old systems we’d held together with chicken wire and prayers were being scrutinized by people who didn’t speak COBOL and weren’t fluent in our business rules. On top of that, like many shops where old systems were backwards-compatible across many years, a lot of our code was built on exceptions — don’t do this for these years, but do this instead for these years. It often took longer to explain why a subroutine wasn’t doing something than to explain what it actually did. We were asked to describe how everything worked, what it connected to, which tables were being accessed and updated, and why a trial balance report with summary totals in the tens of millions of dollars was occasionally out by eleven cents. All while continuing to support these same undocumented systems and attending meetings about replacing them. It was like being asked to narrate an autopsy you were performing on yourself while you were still alive, conscious, and having waived the offer of opiates.
And it wasn’t as if each of us could speak intelligently on all of our systems and processes to the project manager in charge of modernization. There was no formal documentation to pass off to them, except for maybe an incomplete WordPerfect document or Lotus 1-2-3 spreadsheet that we started back in 1993 and saved on a 3 ½-inch floppy disk. So, while we all had a cursory familiarity with everything, the lack of formal documentation coupled with cross-training that didn’t happen meant that staff availability became an issue as well. Discussions related to describing each system needed to be scheduled with the one person who really knew that system.
As a matter of fact, in Part 3 of this series, I spoke about the problems that arose from us not prioritizing cross-training when I said, “The consequences of that? Let’s just say they deserve their own chapter.” And now I’m devoting an entire section of another article to that very topic! It’s almost as if I intentionally dropped a hint about something that I would speak about in greater depth later on, a literary device known as?…anyone?…anyone?…
So close…
And finally — the proverbial cherry to top off our sundae of disquiet — retirements in our department began. It started to feel a little like a game of Digital Division Jenga, with each retiree pulling out a block before they turned off their office lights for good. Only in this version of the game, when the tower collapses, the player heading out the door doesn’t lose — but everyone else left behind does.
It was the perfect storm:
We had an ancient, massive, uncharted set of integrated processes and systems with embedded business rules that we suddenly needed to describe to someone else.
We still needed to maintain this legacy system while the modernization project was taking place.
Legacy staff, the very people who could best describe and maintain the parts of the system that they were most familiar with, started to retire. And when they did, not only did their knowledge leave with them, but there was now one fewer person remaining to help manage all things legacy, including documentation.
It became a ticking time bomb. Or, maybe I should say, “IT” became a ticking time bomb.
The Documentation Dilemma
In theory, formally recording processes is supposed to be the backbone of any well-run system. You write things down so they can be understood, maintained, and eventually handed off. There are all manner of diagrams, flowcharts, and user manuals that explain what the system does, how it does it, and the tables it requires — along with contingency procedures for those rare business scenarios that surface every four or five years. There’s a document that outlines all the testing and validations the system underwent, and release notes for each time components are updated to fix bugs or add features. And then, since no one person should be the sole keeper of a critical process, knowledge transfer plans are created to ensure someone else can helm that particular ship when the time comes.
In practice? Most of us were too busy extinguishing fires to worry about flowcharts. And, although I will be writing this through the lens of my own experience, this is not an IT-specific issue — every profession has its version of the flowchart no one finishes.
Across Canada — especially in long-tenured IT departments — mapping out system processes has often been treated like a gym membership: a worthy idea that, in spite of all the hard work and time commitments, would provide many obvious, positive benefits. Then things get busy with “real work” and you start skipping “data flow diagrams day” like it was leg day. Before long, skipping becomes habit.
“Well,” you say to yourself, “at least I’ve started! Surely something good has come of it!”
It hasn’t. (And don’t call me “Shirley”.)
You see, just like the reality that sets in when you feast your gaze upon your less-than-chiseled physique in the mirror after three 15-minute gym visits, you aren’t going to see any immediate, tangible benefits from the documentation you have just done. Like all things that are worthwhile, it takes time.
And then it gets worse. You start to deprioritize documentation — not because it’s unimportant, but because the results are invisible, which fosters discouragement and leads to even more deprioritization. Before you know it, documentation gets shelved indefinitely (if not abandoned altogether), just like going to the gym. Which, after all, is understandable. Because really — what are you getting out of the process? Doesn’t seem to be much, really.
To better illustrate my point, I’ve created the table below which looks at the desired outcomes common to both a gym membership and documentation and why you’re not getting them.
Table 1. Source: Author’s lived experience, 1990–2025. Unpublished. Also undocumented. Study participants were drawn from various public sector IT departments.
| Desired Outcome | Gym Membership | Documentation Effort |
|---|---|---|
| Applause | Everyone’s too busy admiring their own form in the mirror to notice you showed up. | No one claps for drawing a flowchart — it’s a doodle that gets ignored in less time than it took to draw. |
| Sense of Accomplishment | You bench-pressed a personal best… then threw your back out doing a victory dance. | You documented a system that was built when you were three years old… and now you have to support it indefinitely. |
| Six-Pack | You permanently replaced thrice-weekly ab workouts with a loosely observed regimen of "mindful breathing" and "hydration". | Your boss isn’t buying you beer just because you diagrammed a legacy subroutine. |
So maybe the worst thing that will happen by ignoring the paper trail is the occasional voodoo doll lovingly fashioned in your effigy by your successor when something breaks. And while we may try to convince ourselves that it’s only a temporary thing, that we’ll get back into the swing of things once our lives settle down a bit, we all really know what will happen with that user manual you were working on. It’s going to wind up on your closet floor right beside your complimentary Planet Fatness gym bag, collecting dust and as forever unfinished as Schubert’s Eighth Symphony or that last sit-up you attempted. The sweat was real, but the payoff was theoretical. All you have to show for your effort is a folder no one opens, completely empty save for a doodle that no one recognizes as a flowchart.
And so it goes for many public sector organizations, where inherited systems are still running on arcane logic, tribal knowledge, and the hope that Grace doesn’t retire before fiscal year-end. For example, the 2023 Report 7 from the Auditor General of Canada, titled Modernizing Information Technology Systems, confirms that federal departments are struggling with aging infrastructure, undocumented processes, and a retiring workforce. Among its findings:
• “The old systems require extensive, costly operational support, and they need the support of personnel with knowledge of and expertise on these systems.”
• “Departments were not providing timely, accurate, or complete information about the health of their systems, which made it difficult to prioritize upgrades.”
• “The government faces risks to the continuity of services if it does not modernize aging systems and ensure that knowledge is transferred before experienced personnel retire.”
In other words, our federal government is facing the same ticking time bomb we did — undocumented systems and knowledge playing a game of chicken against the oncoming bullet train of modernization.
Beyond IT — The Hidden Factory of Undocumented Work
This is not just a problem related to computer systems. From back-office operations to manufacturing floors, undocumented processes are silently sabotaging productivity, compliance, and continuity. In finance and HR, undocumented workflows lead to inconsistent performance, onboarding delays, and audit risks. In engineering and design, informal habits and memory-based processes can derail entire projects when the original team moves on. Whether it’s a spreadsheet macro in accounting or a machine’s lever wired into place on the shop floor, undocumented fixes are everywhere.
In manufacturing, they have something called the “hidden factory” — all the undocumented workarounds and off-the-books adjustments that keep things running, but that also undermine quality and consistency. In IT, this happens as well. Sometimes, unique and rare scenarios arise whereby a legitimate change needed to be made but the system logic was preventing it from happening and someone else from doing at least part of their job. The solution is a quick back-door fix: manually changing data, temporarily tweaking code, bypassing validation rules — all done to keep the system afloat and minimize someone else’s down time, then quietly reversed before anyone noticed. These weren’t acts of sabotage; they were acts of survival.
But like the hidden factory, they relied on tribal knowledge and undocumented logic. And when the person who knew the workaround retired, the fix retired with them. So while these practices should never have been invoked in the first place, they still need to be recorded. Documenting informal patches and bad practices isn’t about justifying them. It’s about understanding what’s broken, why we’re compensating for it, and how to build something better to replace it. Because when someone else’s work grinds to a halt and the fix is a workaround no one understands, the result is always the same: confusion, risk, and a lot of panicked finger-pointing and shrugged shoulders.
My experience — scrambling to explain undocumented systems while still supporting them — isn’t unique. It’s happening in departments across the country and across industries. Which, in a weird sort of schadenfreude kind of way, makes me feel better. Our nonchalant approach to documentation could never be mistaken for a best practice. But at least it was (and still is) a common one.
Reflection
It would be far too easy and glib of me to justify my indifference to documentation by saying “Well, no one else seems to be prioritizing this. I’m not going to lose any sleep over it either.” Because in hindsight I likely should’ve carved out a tiny part of my career to become a champion for this cause.
I could’ve created a handover template for the programs and routines I built and maintained. I could’ve consulted with others in our shop to test the template. Maybe even helped define a standardized version we all could’ve used. And yes, I would’ve printed it all off and filed it in the credenza — right next to that 3 ½-inch floppy disk from 1993. And then, later on, I would’ve moved electronic copies of everything into one of those fancy highfalutin shared network folders.
It would’ve been a perfect opportunity for me to be proactive in the creation of something that paid its largest dividends in my own absence. To plant trees the shade of which I would never enjoy.
Could’ve. Would’ve. Should’ve
Didn’t.
Lesson Learned
If I could offer one piece of advice to anyone working with a well-established set of systems or procedures, it’s this: document everything like it will all be retooled starting tomorrow. Because one day you’ll be gone, and some other poor schmo will be left behind to inherit your mess — as ill-equipped as Julia Child in a kitchen without butter or cream. And they’ll be left to describe the workplace you’ve bequeathed them in solemn resignation with the words:
“Abandon hope, all ye who enter here.”
— Dante Alighieri, The Divine Comedy: Inferno, Canto III, line 9 (circa 1320)
OK, maybe that’s a bit dramatic. It’s not like the front door to the office is actually the gates of hell just because a few data flow diagrams are missing. But if the toilet paper’s single-ply and the only coffee option is decaf on top of it all — well, then, welcome to The Seventh Circle!
A written handover isn’t a luxury. It’s a life raft you build for someone else. The systems, processes and workflows we support are already fragile enough without adding systemic memory loss to the mix.
Being the only person who understands something does not make you indispensable. Instead, it means you’ve stamped your knowledge with an expiration date — and that’s the day you walk out the door. The real value isn’t in being the keeper of the knowledge. It’s in making sure the knowledge survives you. Whether it’s an antiquated computer system, a payroll process, or a filing cabinet full of post-it notes, someone’s going to inherit it. And they’ll need a map.
So if you’re still in the trenches and battling infernos with a water pistol, do yourself a favour: put down your Super Soaker and start writing stuff down. Even the weird stuff. Especially the weird stuff. Because someday, someone will need to know why that report crashes when it’s run on February 29th.
Let’s face it: This won’t stop your adoring coworkers from crafting a voodoo doll in your likeness. But it might just keep them from delivering that extra pin to the spleen.
Like what you read? I write, rewrite, overthink, rewrite again, and eventually post these things in hopes they resonate. If something struck a chord, sparked an idea, or — most importantly — made you laugh, please drop a comment below. Sarcasm is welcome, cruelty is not. So be honest, and be nice. It’s possible to do both.
And if you'd like to support the effort (or just bribe me to keep going), you can buy me a coffee. No pressure — but caffeine is a powerful motivator.
Full disclosure: you can’t actually make me buy a coffee with your donation. I might use it for a beer instead.