The blue light of the monitor is doing something rhythmic to my retinas, pulsing in time with the bass line of ‘The Chain’ that’s been stuck in my head for exactly 5 hours. It’s that part where the song breaks down, the tension coiled like a spring, and then the kick drum hits. That’s how the office feels at 4:45 on a Tuesday after the primary database decided to take an unscheduled sabbatical. My fingers are hovering over the keys, but I’m not typing code; I’m staring at a blank Confluence page titled ‘Post-Mortem Lessons Learned.’ My boss, a person who treats ‘best practices’ like a religion they only practice on holidays, just walked by and said those three fatal words: ‘Just document it.’

It sounds so reasonable, doesn’t it? If we just capture the knowledge, we won’t fall into the same pit of fire next time. But as I sit here, my brain feels like it’s been put through a woodchipper, and the only thing I can think about is that if I spend the next 25 minutes writing down why the server failed, I will be 25 minutes late to the meeting about why the *next* project is already 5 days behind schedule. This is the great lie of modern management: the idea that documentation is a secondary task that can be squeezed into the margins of survival.

The Wildlife Corridor Planner’s Dilemma

Quinn B.-L. knows this struggle better than anyone I’ve ever met. Quinn is a wildlife corridor planner-a job that sounds romantic until you realize it involves arguing with 45 different municipal stakeholders about where a mountain lion is allowed to cross a highway. We were talking last week about the documentation of migration patterns. Quinn’s team had spent 15 months tracking a specific set of elk, collecting 4005 distinct data points. When the grant money started to dry up, the directive from the higher-ups was-you guessed it-‘just document the process’ so the next team could take over.

Quinn looked at me with the eyes of someone who hasn’t slept since 2015 and said, ‘They want me to write a map for a forest that is currently on fire. By the time I finish the manual on how to track these elk, the elk will be dead, the highway will be a six-lane toll road, and the software I used to map the terrain will be 5 versions out of date.’

There is a specific kind of exhaustion that comes from being asked to build a library while you are still trying to put out the fire in the basement. It’s not that we are lazy. It’s not that we don’t value ‘institutional knowledge.’ It’s that the very structure of our work is designed to prioritize the *now* at the absolute, violent expense of the *next*. We are incentivized to be firefighters, yet we are judged on our ability to be historians. You cannot be both at the same moment. The adrenaline required to fix a critical system failure is the literal chemical opposite of the slow, reflective state required to explain *how* you fixed it for a future reader who doesn’t exist yet.

The Ghost of a Dead Crisis

[The document is the ghost of a dead crisis.]

I’ve made this mistake myself, many times. I remember a project about 5 years ago where I thought I was being a hero. I spent 85 hours building a custom automation script that saved the company about $555 a month in manual labor. I was so proud of it. But when it came time to write the documentation, I was already being pulled into a ‘Level 1 Emergency’ regarding a client’s lost data. I figured I’d write the README later. I never did. Two years later, that script broke. The guy who had to fix it was a junior dev who had no idea I even existed. He spent 35 hours trying to reverse-engineer my ‘heroism.’ My lack of documentation didn’t just negate the money I saved; it actually cost the company more in the long run because I hadn’t been ‘allowed’ the time to finish the job.

But here is the contrarian bit: even if I *had* written it, would he have found it? Most corporate wikis are less like libraries and more like the Winchester Mystery House-staircases that lead to nowhere, doors that open into brick walls, and rooms filled with the furniture of people who left the company in 2005. We treat documentation as a storage problem when it is actually a maintenance problem. A document that isn’t updated is a lie. And in an environment where we are ‘too busy to document,’ we are certainly too busy to update.

Organizations want living knowledge, but they want it for free. They want the resilience that comes from a well-documented system, but they don’t want to fund the 25% overhead it takes to keep that system accurate. They treat it like a tax they can just avoid paying if they run fast enough. But the tax always gets collected. Usually, it’s collected at 3:15 AM on a Saturday when the only person who knows how the legacy API works is on a cruise ship in the middle of the Caribbean.

The Underpass Weeds

Quinn B.-L. told me about a corridor they designed in the Pacific Northwest. It was a beautiful piece of engineering-underpasses lined with local flora, acoustic dampening for the truck noise, the works. But the ‘documentation’ for the maintenance crew was just a 115-page PDF that sat in a drawer. Nobody read it. Within 5 years, the local maintenance crew had ‘cleaned up’ the underpass by removing all the ‘weeds,’ which were actually the specific plants the deer needed to feel safe enough to cross. The system failed because the knowledge wasn’t integrated into the work; it was just a file on a shelf.

This is why I find the approach at tded555 so vital-it’s the recognition that systems aren’t just technical; they are operational and deeply human. If the operational reality doesn’t allow for the maintenance of the system, the system is a ticking time bomb. You can’t just wish clarity into existence; you have to build a schedule that permits it.

The Trade-Off

I’m still humming that song. *Listen to the shadows, search for the answer.* The answer, I suspect, is that we need to stop nodding when managers say ‘just document it.’ We need to start saying, ‘Which of these 5 priority tasks should I drop so that I can document this properly?’ We need to force the trade-off into the light. If documentation is important, it needs a ticket. It needs a deadline. It needs a budget. If it’s just something we’re supposed to do in our ‘spare time,’ then it’s not a priority; it’s a fantasy.

I remember another time Quinn B.-L. had to present a plan for a new bridge. The board wanted to know why the ‘administrative and recording’ phase cost $75,000. Quinn told them, ‘Because if I don’t record why we chose this specific slope for the bridge, ten years from now, someone will try to “optimize” it, and the grizzly bears will go back to crossing the pavement. You aren’t paying me to write a report; you’re paying me to make sure the bridge keeps working after I’m gone.’

That’s the shift. Documentation isn’t a chore; it’s the bridge between the present and the future. But you can’t build a bridge with the leftovers of your energy. You can’t build it while you’re sprinting away from a fireball.

A Small Victory

I look back at my blank screen. The cursor is still blinking. 55 minutes have passed since I started ‘documenting.’ I’ve written three sentences and spent the rest of the time thinking about Quinn and elk and Fleetwood Mac. I realize that I’m trying to perform the ritual of documentation without the substance of it. I’m doing it to check a box, to satisfy a manager’s wishful thinking.

So, I do something brave. Or maybe something stupid. I close the tab. I open the Jira board. I create a new ticket: ‘Technical Debt: Core Database Recovery Documentation.’ I assign it 8 hours. I move it to the top of the next sprint. Then I walk over to my manager’s desk.

‘I’m not going to document the outage tonight,’ I say.

They look up, surprised. ‘Why not?’

‘Because I’m too tired to be accurate, and a wrong document is more dangerous than no document. I’ve scheduled it for Thursday morning when I can actually think. Which of the 5 tasks on my plate for Thursday should I move to Friday?’

There’s a long silence. Maybe 15 seconds. It feels like an hour. But then, they nod. It’s a small victory, but it’s a real one. It’s the refusal to participate in the charade. We need to stop pretending that knowledge is something that just happens. It’s something that is built, brick by painful brick, and you can’t lay bricks while you’re running for your life.

I leave the office while the sun is still up, which feels like a miracle. The song in my head has finally changed. It’s slower now. More deliberate. I think about Quinn’s elk, moving through the woods, following paths they didn’t have to map because the paths were built into the earth itself. That’s the dream, isn’t it? To build systems so clear that they document themselves. But until then, I’ll take a scheduled Thursday and a honest conversation over a ‘living document’ that’s actually been dead for years.

The Question Lingers

How many hours of your life have you spent looking for a piece of information that someone was ‘too busy’ to write down? How many times have you been that person? We’re all just curators of a museum that’s constantly being renovated while the guests are still inside. Maybe it’s time we closed the doors for a day and actually labeled the exhibits.