Sofia leaned so far into her monitor that the bridge of her glasses nearly touched the anti-glare coating, her shoulders hiked up to her earlobes in a classic structural defense mechanism against impending failure. She was on day three of her new role as a senior engineer, and she was currently losing a wrestling match with a local environment setup that, according to the company’s sprawling Notion workspace, should have taken exactly twelve minutes.

The “Getting Started” page was a masterpiece of digital curation. It featured custom icons, a multi-level taxonomy, and a header image of a serene mountain range that implied the engineering culture here was one of quiet, contemplative triumph.

Sofia checked the “Last Edited” timestamp at the bottom of the portal page. It was fourteen months ago. The mountain range suddenly looked less like a symbol of peace and more like a monument to a forgotten civilization.

When she finally gave up and posted the error in the #dev-onboarding Slack channel, the response was instantaneous. Three different people reacted with a “face-palm” emoji. A fourth person, a staff engineer named Marcus, pasted a snippet of code that fixed the issue immediately and then typed the words that every frustrated new hire eventually hears:

“Oh, yeah, the wiki is out of date. Just look at dev-notes.md in the root of the main repo. It’s in the second to last section. We keep meaning to move it over to the portal.”

– Marcus, Staff Engineer

The Triumph of the Ugly File

Sofia opened the file. It was a sprawling, 900-line disaster of a Markdown document. There were no custom icons. There were three different types of heading styles used inconsistently. There was a section at the bottom titled “CRAP THAT BREAKS EVERY TUESDAY,” written in all caps. It was ugly, it was disorganized, and it was 100% correct.

We spend millions of dollars every year funding the appearance of knowledge while starving the actual transmission of it. The uncomfortable truth of modern software development-and perhaps all information work-is that any documentation system that requires a user to leave their primary workflow is not a documentation system. It is an archive.

I recently tried to replicate a floating bookshelf I saw on Pinterest. It was a classic “DIY” project documented through a series of sun-drenched photographs and a list of five simple steps. The documentation was designed for me, the reader, to feel inspired.

However, it failed to mention that the specific 2x4s sold at the local hardware store are rarely straight, or that the weight-bearing capacity of a drywall anchor is a polite fiction if your house was built before 1970. I ended up with six unnecessary holes in my wall and a pile of splintered pine because the documentation was designed to look “done,” not to be “doing.”

Proximity Over Polish

The messy dev-notes.md file in Sofia’s repository won because it lived where the work lived. The cost of updating it was eleven seconds. An engineer discovers a bug, fixes it, and realizes they never want to deal with it again, so they tab over to the file they already have open in their IDE and jot down a frantic, ungrammatical warning.

There is no “Publish” button to hit. There is no taxonomy to navigate. There is no fear of ruining the “aesthetic” of the corporate knowledge base. Documentation projects fail because they are designed for the consumer of information rather than the producer of it.

When we build these beautiful portals, we are optimizing for the “Reading Experience.” We want it to be searchable, pretty, and professional. But the act of creating documentation is a high-friction event. It is a secondary task that competes with the primary task of shipping code or solving problems. Or, if they’re feeling generous, it will end up in a messy text file that actually works.

The industry has a strange obsession with the “Artifact of Record.” We want a single source of truth that looks like a textbook. But in a fast-moving environment, the only real source of truth is the byproduct of the work itself. This is why the best engineering teams have moved away from “documentation phases” and toward “living artifacts.”

Integrated Delivery Beats the Manual

When a team is integrated correctly-like the squads at

Digital Heroes-the documentation isn’t a separate chore that happens at the end of a quarter. It’s baked into the rhythm of delivery.

They don’t just hand over a finished product and a “Manual” that will be obsolete by the first patch. They transfer a record of architecture, weekly demos, and release notes that were generated as the code was being written. The goal isn’t to create a beautiful library; it’s to ensure that the person who inherits the codebase six months from now has a map that actually matches the terrain.

We mistake the artifact’s appearance for its function. A perfectly formatted wiki page with a broken code snippet is a liability. A messy text file with a working solution is an asset. Yet, when budgets are allocated, we consistently fund the portal and ignore the process.

We hire “Knowledge Managers” to organize the archive, but we don’t give the engineers the three minutes of breathing room required to keep the notes.txt file from becoming a labyrinth.

The frustration Sofia felt-the physical tension in her neck and the slamming of her palms-is the body’s reaction to a systemic lie. She was promised a mountain range and given a pile of red text. If you want to know the health of a project, don’t look at the Notion board. Don’t look at the Confluence tree. Ask for the “Notes” file. Ask for the “README” that hasn’t been formatted.

Look for the file that has the most recent commit message saying “added fix for the weird build error.” The most valuable documentation in any organization is usually the stuff that looks the worst. It’s the “Things that will break” section. It’s the “Don’t touch this or the server explodes” comment.

We need to stop designing for the person who wants to read about the work and start designing for the person who is currently doing it. This means embracing lower-fidelity formats. It means prioritizing proximity over polish. It means admitting that a document’s value is measured by its accuracy, not its font choice.

I’ve spent years studying body language, and the one thing that never lies is the “Micro-Shift.” It’s that tiny adjustment someone makes when they are about to say something they don’t quite believe. When a manager points to a pristine documentation portal during a demo, you can often see the engineers in the back of the room make that shift. They know.

They know where the real notes are. They know which files are the “truth” and which ones are the “costume.” The next time you’re tempted to spend a week “cleaning up the wiki,” stop. Don’t move the messy notes into the portal. Instead, figure out why the notes were in the repo to begin with.

Embracing the Truthful Mess

It’s because the repo is where the work is. If you want better documentation, make it easier to write, not easier to read. Strip away the templates. Get rid of the mandatory screenshots. Allow the “CRAP THAT BREAKS” sections to exist. If we want to build things that last, we have to stop being so afraid of the mess.

The mess is where the truth lives. Sofia didn’t need a mountain range; she needed a line of code that worked. She found it in an 800-line text file that everyone “meant to move” but never did.

Thank god they didn’t. If they had moved it to the portal, someone would have probably deleted the “ugly” parts, and Sofia would still be sitting there, shoulders up to her ears, staring at a screen full of red.