The wrench slipped again, leaving a fresh, jagged scratch on the porcelain of the aft-starboard head. It was 3:02 AM. I was covered in grey water and a specific kind of frustration that only emerges when you realize the person who wrote the maintenance manual for a submarine’s plumbing system apparently never actually held a wrench while submerged. They had written it from a desk, probably in a room with windows and air that didn’t taste like recycled diesel and desperation. This is the same feeling I get when I open an internal wiki to find a ‘Simple Setup Guide’ for a remote access gateway. It is a physical sensation of being lied to by someone who isn’t even there to apologize for it.
The Structural Collapse of Organizational Truth
You stare at the screen. The instructions say, ‘Navigate to the 2022 Management Console.’ You look at your environment. You are running a legacy stack that looks like it was cobbled together during the first Bush administration, and the server referenced in the documentation was decommissioned 12 months ago. There is a screenshot-blurry, cropped so tight you can’t see the context-of a button that no longer exists in the current UI. This is not just a ‘writing problem.’ This is a structural collapse of organizational truth. When an engineer opens a guide to provision access for a new contractor and finds a dead link to a retired LDAP server, they aren’t just losing 22 minutes of their life. They are learning that the official record is a work of fiction.
“The wiki is a graveyard of intentions.”
The Lie is What the Manager Wants to See
We treat documentation like a chore we’ll do ‘once things settle down.’ But things never settle down. On a boat, if I don’t document how many 12-ounce cans of tomatoes I have left, someone eventually eats a very sad, very dry pasta 22 days into a patrol. In IT, if the documentation for a remote desktop environment isn’t updated to reflect the actual licensing server IP, a whole department sits idle on a Monday morning. The documentation failure is evidence that the organization doesn’t actually agree on how the work happens. If the ‘Process’ says A-B-C, but the ‘Reality’ is A-D-B-F, the wiki will always reflect the lie because the lie is what the manager wants to see. It’s a performative act of order.
The Cost of Guesswork
Time spent on 3 AM plumbing
Experience required to bypass manual
I fixed that toilet at 3:02 AM by ignoring the manual and feeling for the tension in the valve. It was an intuitive leap born of 12 years of handling broken things. But you shouldn’t have to be a ‘hero’ or a ‘wizard’ to set up a remote gateway. The obsession with the ‘hero engineer’ who knows all the secrets is actually a symptom of a failing system. When you are looking for clarity on your
windows server 2022 rds user calrequirements, and the internal documentation suggests you just ’email Dave,’ Dave becomes a single point of failure. If Dave gets hit by a bus-or more likely, if Dave takes a job that pays 32 percent more at a firm that actually maintains its documentation-the organization suffers a collective lobotomy.
Building Traps, Not Failovers
It’s funny, actually. I hate writing these things. I’m a submarine cook, not a technical writer. I prefer the immediate feedback of a well-salted broth or a perfectly timed loaf of bread. But even I can see the rot. We pretend that ‘updating the docs’ is a discrete task, like taking out the trash. It’s not. It is the work. If you haven’t documented the 52-step process for a failover, you haven’t actually built a failover; you’ve built a trap. You’ve built a scenario where you are betting on your future self’s memory, and your future self is going to be tired, stressed, and probably dealing with a 3:02 AM plumbing emergency.
OBSERVATION: Standing Around the Hole
I remember a specific incident where we were trying to troubleshoot a communication lag. The ‘Official Guide’ had been updated ‘recently’-or so the timestamp said. But the comments underneath were a tragedy in 12 acts. One engineer had posted 62 days ago that the primary gateway IP was incorrect. Another had replied 42 days ago saying they found the correct IP but weren’t sure if they should edit the page. A third had simply posted a ‘?’ 2 days ago. Nobody had changed the actual page. They were all standing around a hole in the ground, politely discussing the depth of the hole, while people kept falling into it.
This ‘polite desperation’ is the death knell of trust. When a junior admin follows a guide to the letter and it results in a system crash, we often blame the admin. We say they lacked ‘common sense.’ But ‘common sense’ in IT is often just a collection of scars from previous documentation lies. We are teaching people that the official word of the company is garbage. We are training them to ignore the manual and seek out the ‘Daves’ of the world. And then we wonder why our onboarding takes 92 days instead of 12.
The value of admitting a visible mistake.
I’m a big fan of the ‘vulnerable mistake.’ I’ll admit I once accidentally used salt instead of sugar in a batch of 222 cookies. I had to throw them all out. The mistake was visible, public, and corrected. Documentation needs to be the same way. It needs to admit where it is weak. I would rather see a wiki page that says ‘We don’t know how this part works’ than one that provides 12 steps of outdated fiction. At least the ‘we don’t know’ is honest. It allows the next person to approach the problem with their eyes open, rather than walking blindly into a 2012-era configuration error.
Honesty is a technical requirement.
The True Cost of Digital Archaeology
Think about the numbers for a second. If you have 22 engineers, and each of them wastes 12 minutes a day looking for a piece of information that is incorrectly documented, that’s over 4 hours of lost productivity every single day. Over a year, that’s more than 1002 hours. You could have built a whole new subsystem in that time. You could have automated the very process that people are struggling to document. Instead, you are paying your most expensive assets to be digital archaeologists, digging through layers of ‘New_Doc_Final_v2.docx’ to find the one true version of the truth.
Productivity lost due to documentation decay.
It comes back to the submarine. On a boat, we have ‘DC Books’-Damage Control books. They are kept in 12 different locations. They are updated with physical pens. If a pipe is moved 2 inches to the left to make room for a new oxygen scrubber, the DC Book is updated that day. Why? Because if the boat starts taking on water, you don’t have 22 minutes to ‘ping Dave’ on Slack to ask where the isolation valve is. You need to know now. IT environments might not sink to the bottom of the ocean, but the ‘sinking’ of a business due to prolonged downtime is a very real, very cold reality.
The DC Book Standard
If a pipe is moved 2 inches to the left to make room for a new oxygen scrubber, the Damage Control Book is updated that day. Documentation must be treated as critical infrastructure, updated immediately upon change, because failure to do so leads to immediate, catastrophic operational risk.
We need to stop treating documentation as an extra-credit assignment. It is the infrastructure itself. A Windows Server 2022 instance without an accurate configuration record is just an expensive heater. It’s a promise we haven’t kept. And the longer we leave those broken promises in the wiki, the more we tell our teams that their time doesn’t matter, that the ‘truth’ is whatever the loudest person remembers, and that the ‘official’ way of doing things is just a suggestion for the uninitiated.
The Sharpie Truth
I finished fixing the toilet eventually. I didn’t use the manual. I used a flashlight, a mirror, and a lot of swearing. But as I was cleaning up the mess, I took a Sharpie out of my pocket. I wrote the actual valve sequence directly on the bulkhead in 2-inch high letters. It wasn’t ‘official.’ It wasn’t ‘clean.’ It didn’t go through a 12-person approval workflow. But the next person who has a 3:02 AM emergency isn’t going to have to guess. They aren’t going to have to wonder if the documentation is lying. The truth is right there on the wall, written in permanent ink by someone who actually did the work.
Less Polite Desperation, More Ink.
“We need to stop pretending our systems are perfect and start documenting the reality of the mess we’ve actually built. Only then can we stop the bleeding of trust and start building something that actually stays afloat when the pressure starts to rise.”
If you can’t tell me how to fix it in 12 minutes, you haven’t documented it; you’ve just told a story about how you wish it worked.
