The Documentation That Doesn't Exist
Stefan asks for architecture docs and discovers there are none. He asks for a deployment runbook and gets the same answer: 'Tomasz knows how.' With Tomasz's departure date counting down and the studio still one sickness away from total paralysis, Stefan sits down with Tomasz and starts pair-documenting. Not a polished wiki. Not a consulting deliverable. Just the minimum set of truths that keep a system alive: what exists, why it exists, and what breaks when you touch it.
Monday, 09:12 — The Empty Wiki
“Where are the architecture docs?”
Stefan asked it the way you ask where someone put the keys.
Katja blinked once, as if she hadn’t heard the question correctly.
Tomasz didn’t blink at all. He just stared at the screen, at the blank Confluence space Katja had pulled up because it was the fastest way to answer.
No pages.
No diagrams.
Not even a sad little “TODO”.
The emptiness was clean enough to be insulting.
“We…” Katja started, then stopped because there was no honest sentence that began with we and ended with have documentation.
“It’s in my head,” Tomasz said.
He said it flat, like a weather report.
Stefan nodded once. Not surprised. Not impressed.
“Okay,” he said. “Where is the deployment runbook?”
Katja clicked out of Confluence and opened the shared drive, because that was the other place a company pretended knowledge lived. She typed “deploy” into search. It spun for two seconds and returned a list of old screenshots and a PowerPoint from 2021 titled “Release Process (draft)”.
The first slide was a diagram of a pipeline Pixel Spree no longer had.
Tomasz made a sound that might have been a laugh in a different life.
“Hassan knows how,” Katja said.
“Hassan is out sick,” Stefan said.
“He came back this morning,” Katja said quickly. Too quickly. Like she was talking about a fragile object she didn’t want Stefan to touch.
Stefan leaned back in his chair and looked at Tomasz.
“How many working days?” he asked.
Tomasz’s jaw tightened. Then he exhaled.
“Fifty-six,” he said.
Katja looked between them. “You’ve been counting?”
“Of course I’ve been counting,” Tomasz said. “It’s the only countdown in this place that actually ends.”
Stefan uncapped his pen and wrote 56 in his notebook.
“We’re not building a documentation program,” he said. “We’re not migrating to a new wiki. We’re not doing a workshop.”
Katja’s shoulders dropped an inch, relief mixing with something else.
“Then what are you doing?” she asked.
Stefan turned his notebook toward them. It was already open on a blank page.
“We’re writing down the smallest set of things that keeps the system alive when you leave,” he said, nodding at Tomasz.
Tomasz’s eyes flicked to the notebook, then away.
“You can’t write down two years in fifty-six days,” he said.
“We’re not writing down two years,” Stefan said. “We’re writing down the reasons your future self would yell at you for forgetting.”
Tomasz’s mouth twitched. Not a smile. A crack.
“And when we’re done?” Tomasz asked.
Stefan’s voice stayed calm.
“Then it exists somewhere other than your skull,” he said. “Which means it exists.”
Monday, 13:40 — A File Called README
Tomasz hated writing.
Not the act of typing.
The act of freezing something.
Code moved. Docs didn’t. Docs fossilized decisions and then mocked you for changing them.
But Stefan didn’t start with a diagram.
He started with a file.
“Name it,” Stefan said.
“Architecture Overview,” Tomasz said, already irritated.
“No,” Stefan said. “Name it like you’re talking to Emma on her first on-call night.”
Tomasz stared at him.
“She’s not on-call,” Tomasz said.
Stefan’s pen paused.
“Then you have an on-call problem too,” he said.
Tomasz looked away.
“Call it README,” Stefan said.
“That’s…” Tomasz started.
“Boring,” Stefan finished. “Good. Boring is survivable.”
Tomasz opened his editor. Created docs/README.md.
The cursor blinked.
He sat there for ten seconds, jaw tight. The room had the particular silence of two people facing an empty page.
Stefan didn’t fill it with words.
He asked one question.
“What is the most dangerous misunderstanding a new developer can have about this system?”
Tomasz answered without thinking.
“That staging is like production,” he said.
Stefan nodded. “Write that first.”
So Tomasz wrote:
- Staging is not production. The load balancer config differs. The database differs. A change that looks safe in staging can take down production.
His fingers moved faster once he started. Not because he liked it.
Because he was finally writing the things he’d been carrying alone.
Stefan watched the words appear. Then he pointed at a sentence.
“Why is it different?” he asked.
Tomasz swallowed.
“Because in 2023 we had a traffic spike and production fell over,” he said. “We patched the load balancer in production. We didn’t backport it to staging because we were in a hurry and then we forgot and then it became normal.”
Stefan wrote PATCHED PROD, NOT STAGING — HURRY BECOMES NORMAL.
“Write that too,” he said.
Tomasz’s hands paused above the keyboard.
“That makes us look stupid,” Tomasz said.
“It makes you look honest,” Stefan said. “Docs aren’t marketing. Docs are confession.”
Tomasz stared at him for two seconds.
Then he typed the sentence.
Tuesday, 10:05 — Hassan Returns
[Image: Hassan at his desk for the first time in a week. Dark hoodie slightly too big, hood down, eyes shadowed, energy drink can near keyboard, hands shaking faintly as he logs into monitoring dashboards. Emma: fitted black t-shirt, ripped jeans, hair in messy bun, leaning on the desk edge with her laptop finally unboxed. Stefan and Tomasz visible in the background in a glass room, writing. Early May morning light, ~18°C.]
Hassan came back without an announcement.
No “I’m back” in Slack.
No apology.
He slid into his chair like a man returning to a crime scene.
Emma was there before he finished logging in.
“Hey,” she said, soft on purpose.
Hassan flinched anyway.
“How bad is it?” he asked.
“Nothing shipped,” Emma said.
Hassan’s eyes closed for half a second.
“Good,” he said.
Emma blinked. “Good?”
“If nothing shipped, nothing broke,” Hassan said. His voice was rough, like he’d been sleeping in the wrong position for a week. “If something shipped, I’d be finding it right now.” He opened the deployment script. The cursor landed on a line marked # DO NOT TOUCH.
Emma pulled her chair closer.
“Stefan found a hardcoded IP address inside a Friday check,” she said.
Hassan’s head snapped toward her.
“He read that?” Hassan asked.
“He read all of it,” Emma said.
Hassan’s jaw clenched.
“Good for him,” he said, not meaning it.
Across the room, Stefan looked up from a doc file and caught Hassan’s eye.
He didn’t wave.
He didn’t smile.
He just raised his pen slightly, a small gesture that meant: I see you. I’m not here to judge you. I’m here to reduce the load.
Hassan looked away first.
His hoodie made him smaller.
His chair made him stuck.
His screen filled with red alerts he’d been dreaming about even while he slept.
Wednesday, 15:18 — The Runbook That Hurts
[Image: Close-up of Tomasz’s hands typing on a laptop. On screen: a markdown file titled “deploy-runbook.md” with sections: “Before”, “During”, “After”, “Rollback”. Stefan’s notebook beside it, blue ink notes. Tomasz’s coffee cup, chipped mug. Warm afternoon light.]
The runbook wasn’t hard because it was complex.
It was hard because it was personal.
“Before a deployment,” Tomasz said slowly, “I check the live ops calendar. Not because it’s in the process. Because if we deploy during a player event, Elif will murder us.” He paused. “Not literally. But she’ll be right.”
Stefan didn’t laugh. He wrote it down.
“Then I check the database replication lag,” Tomasz continued. “If it’s above two seconds, we wait.”
“Where is that documented?” Stefan asked.
“It isn’t,” Tomasz said.
Stefan looked at the screen. “Then write it.”
Tomasz wrote:
- Check DB replication lag. If >2s, pause deploy.
“Why two?” Stefan asked.
“Because above two, we’ve seen the session handler spike CPU during container restarts and it cascades,” Tomasz said, irritation rising. “I don’t know why it’s two. It just is.”
Stefan’s pen stopped.
“You do know why,” he said. “You just don’t want to admit you made up a number in a crisis and then proved it was right enough to keep using it.”
Tomasz’s face flushed.
“Kurwa,” he muttered under his breath.
Stefan raised his eyebrows.
“Write the real reason,” Stefan said.
Tomasz stared at him like Stefan had asked him to write down a secret.
“Because in a crisis,” Tomasz said quietly, “you choose a threshold. You keep it. And then everyone treats it like physics.”
Stefan didn’t let the silence go soft.
“Write that,” he repeated.
Tomasz typed:
- Threshold note: 2s was chosen during a 2023 incident and kept because it prevented cascades. It is an observed guardrail, not a derived law.
The sentence looked ugly.
It looked true.
Tomasz leaned back and stared at it.
“This makes me feel exposed,” he said.
“Good,” Stefan said. “If it feels exposed, it’s probably the part someone needs when you’re gone.”
Thursday, 17:52 — Fifty-Six Becomes Fifty-One
[Image: Stefan and Tomasz standing at a whiteboard. A list of numbers: 56 crossed out, 51 circled. Under it: “Docs shipped” with checkboxes. Tomasz’s hoodie half unzipped, heat in the room. Stefan’s sleeves rolled, notebook closed. Late afternoon spring light turning gold.]
They didn’t document everything.
They documented the dangerous parts.
The parts that, if misunderstood, would kill a week.
They wrote down the names of services that existed only because a crash in 2023 taught them fear.
They wrote down the order of restarts that prevented a cascade.
They wrote down which alerts were noise and which ones meant “wake up”.
Stefan committed the docs to the repository in small chunks, like code. Not a big dump at the end. A stream.
Tomasz watched the commits land like a man watching pieces of himself leave his body.
“Why are you committing this like code?” Tomasz asked.
“Because it is code,” Stefan said. “It changes. It should be reviewed. It should be versioned. It should have history.”
Reader's note: Documentation is code-adjacent operational knowledge, so it belongs in the same repository as the product code. Architecture notes, runbooks, guardrails, migration warnings, rollback rules — if developers need it to ship and recover safely, it is part of the product system.
Keeping that information in separate wikis, slide decks, or shared drives is a delivery dysfunction. It breaks review flow, hides change history, and guarantees drift between reality and explanation. The saying is brutal because it's true: once it's saved, it becomes a lie. Putting docs in the repository is how teams shorten that lie and correct it in the same workflow as code.
In 2026, this also unlocks AI-assisted maintenance: tools can review the actual code, compare it against runbooks and architecture notes in the same repository, and suggest updates when documentation drifts from implementation.
Tomasz nodded once.
Then, quietly:
“Nobody asked for this,” Tomasz said.
“They should have,” Stefan said.
“No,” Tomasz said. His voice tightened. “Nobody asked me. They asked for delivery. They asked for velocity. They asked for more features. They asked for Head of Engineering. Nobody asked for me to be a person with a brain that can only hold so much.”
Stefan didn’t answer with sympathy.
He answered with a practical sentence that landed harder.
“Then this is you asking,” he said. “For the next person not to drown the way you did.”
Tomasz looked at the whiteboard number. Fifty-one.
“I still want to leave,” he said.
“You should,” Stefan said.
The honesty of it made Tomasz’s eyes widen.
“But you don’t have to leave a crater behind you,” Stefan continued. “You can leave a map.”
Tomasz’s throat moved. He swallowed.
“A map,” he repeated.
Stefan capped his pen.
“A map,” he said.
Navigator — Tomasz Kowalski — 8 May 2026, 18:11
I wrote documentation today.
That sentence feels like admitting failure.
For two years I carried everything because it was faster than explaining. Faster than drawing diagrams. Faster than writing notes. Faster than teaching.
Now I’m leaving and suddenly everyone wants the knowledge that made me tired.
Stefan didn’t ask for a wiki. He asked for the parts that kill you when you don’t know them.
It still feels like exposure. Like putting my mistakes on paper.
But it also feels like the first professional thing I’ve done here in months.
🎭 This Week's Episodes
Telenovelas show what we can't say in client meetings. The drama is heightened, but the patterns are real.
La Verdad
The emergency board meeting Don Hernando demanded has arrived. Mariana and the Vulcano Capital team want answers. Alejo has one final card to play....
When Players Revolt
They fixed the validation bug properly — six hours, no corners cut. But the database migration script Anton wrote Monday night to handle legacy NUL...
Technical Consultancy
Senior Developer Advocate
Embedded into your team as an active contributor, increasing effectiveness and elevating engineering clarity.
Technical Advisor
Peer-style technical assessments before far-reaching decisions; reduce architectural and product risk early.
Product & Delivery
Ship working software to real users earlier. Measure impact and adapt based on evidence rather than assumption.
Custom Software Development
High quality, maintainable software. Short-term augmentation that leaves lasting capability in your own team.
Recent Articles
- When Labor Becomes Cheap, Motivation Becomes Everything (06.04.2026)
- Authentication Methods That Work in 2026 (03.04.2026)
- Developer, Not Engineer. And Why It Matters (30.03.2026)
- The Product Manager Is Dead. Long Live the Product Developer. (27.03.2026)
- Building Products in the Age of AI (23.03.2026)
