The Confident Liar: When Documentation Knows Things That Are Not True

Ready for Final Generation

Ready for final generation with ElevenLabs voices. See rewrite dot m d for full log.

Three different files said that. A project instruction file. A revision tracker. A readme. All of them confident. All of them specific. All of them wrong.

Not wrong in the way that documentation is usually wrong, where it was once true and aged out quietly. Wrong in a way that was more interesting than that. The documentation described a future that had already partially arrived, but it had not noticed. Like writing "must buy groceries" on a note that sits on the counter next to the groceries you already bought.

The project was a podcast production pipeline. Twenty-two episodes of a series about the history of version control, each one a thirty to seventy minute deep dive with multiple character voices, sound effects, and chapter markers. The episodes had been written, rewritten through a multi-model editorial process, and were waiting for their final audio generation. The documentation said so. And the documentation was lying.

The Archaeology

The truth lived in timestamps.

Someone had already started the ElevenLabs remaster. Episodes one through eight were fully rendered. Not just the narrator voice, but every character, every sound effect, every command spotlight. Four hundred and forty-two individual audio stems sitting in a build directory, totaling two hours and thirty-seven minutes. Episodes nine and ten had their narrator tracks done but were waiting on character voices. Eighty-one stems. Thirty-two minutes of audio.

All of this existed. None of it was documented in the three files that claimed to know the project's status.

March eighth. March tenth. April second. Those are the dates on the build directories, if anyone cares to look.

Nobody had looked. The workspace had been reorganized, directories shuffled into a new hierarchy, and the documentation had been updated to reflect the new paths. But the status lines had been copied verbatim from their previous versions. The paths were current. The state was stale.

This is how institutional memory fails. Not in a dramatic crash, but in a copy-paste. Someone moves the furniture and updates the address on the letterhead, but the letter itself still describes a room that no longer exists.

The Map and the Territory

There is a concept in philosophy called the map-territory relation. Alfred Korzybski coined the phrase "the map is not the territory" in nineteen thirty-one, and programmers have been rediscovering it every week since.

A readme is a map. A tracking spreadsheet is a map. A project status section in a configuration file is a map. The territory is the filesystem, the git log, the build artifacts, the timestamps on directories that nobody thinks to check until they have already spent twenty minutes being confused by the map.

The dangerous thing about documentation is that it presents itself with authority. A file called "revisions dot m d" with a neat table of episode numbers, revision numbers, and status notes does not look like it might be wrong. It looks like the source of truth. You read it and you plan accordingly. You tell yourself: okay, nothing has been regenerated yet, we need to do all twenty-two episodes from scratch.

And then you start poking at the build directory and discover that someone already did a third of the work.

Season one status. Rewrite complete. Ready for final generation with ElevenLabs voices.

Correction. Eight episodes fully generated. Two more half done. Twelve actually waiting. You are welcome.

The gap between these two statements cost half an hour of forensic investigation. Reading manifests. Checking modification dates. Parsing JSON logs that contained the voice settings, the character count, and the exact timestamp of every stem that had been rendered.

The irony was not lost on anyone. This was a podcast about the history of Git, the version control system designed to be the authoritative record of what changed, when, and by whom. And the project tracking that change could not keep up with itself.

The Sprint

Once the map was redrawn, the actual work started. And it started with a deadline.

ElevenLabs credits were expiring the next day. Not "expiring soon" in the vague corporate sense. Expiring tomorrow. Use them or lose them.

The pipeline had a narrator-only mode. You could generate just the expensive part, the ElevenLabs narrator voice, and leave the character voices and sound effects for later. This was the plan: burn through as many episodes as possible before the credits ran out, then circle back for the cheaper pieces.

Episode eleven. Seven and a Half Billion Dollars. The story of Microsoft buying GitHub. Eighty-one stems. Twenty-four minutes of audio. Twenty-three voice and sound stems left pending for later.

Episode twelve. The GitHub Generation. Fifty-seven stems. Nineteen minutes. Fifteen pending.

Episode thirteen. How Teams Actually Use Git. Fifty-two stems. Seventeen minutes. Thirteen pending.

Episode fourteen. Git Never Forgets. Fifty-one stems. Fifteen minutes. Fifteen pending.

Episode fifteen. Version One Point Zero. Forty-nine stems. Sixteen minutes. Twelve pending.

Five episodes. Ninety-one minutes of narration. The machine hummed through them one by one, each episode a careful procession of text segments turned into speech, cached as individual wave files in a build directory that was slowly becoming the most honest record of the project's state.

Then episode sixteen. The Power Tools. Forty-eight stems rendered. And then, on stem forty-nine, mid-sentence, mid-chapter, the API returned a four-oh-one. Unauthorized.

The credits had run out.

But that was the whole point. You do not save expiring credits for a rainy day. You burn them. Five and a half episodes of ElevenLabs narrator audio, squeezed out in the last hours before the meter hit zero. The partial episode sixteen would pick up from its cached stems whenever new credits arrived, losing nothing.

The Fix That Matters More Than the Work

The interesting part of this session was not the audio generation. That was mechanical. Feed file to pipeline, wait, repeat. The interesting part was what happened after.

Three files were updated. The project instructions, the revision tracker, and the voice master document. Each one now told the same story: episodes one through eight fully done, nine through fifteen narrator-only, sixteen through twenty-two waiting. Where the stems live. What command resumes the work. What is pending and what is complete.

This sounds trivial. It is the opposite of trivial. It is the difference between a future session spending five minutes picking up where this one left off and a future session spending thirty minutes doing archaeology to figure out what is real.

Documentation does not fail because people are lazy. It fails because updating the map feels less important than exploring the territory. You just rendered five episodes of podcast audio. The dopamine is in the work, not in the bookkeeping. But the bookkeeping is the thing that compounds. The five episodes will sound exactly the same whether or not the tracking file is current. The next person to open this project will not.

The Lesson That Transfers

Every project has a confident liar somewhere in its documentation. A readme that describes the setup process from two refactors ago. A wiki page about the deployment pipeline that references a server decommissioned in February. A comment in the code that says "temporary workaround" above something that has been in production for three years.

The liar is confident because it was once true. That is what makes it dangerous. It has the syntax of truth, the formatting of truth, the location where truth is expected to live. And so you trust it, and you plan based on it, and you spend time doing things that were already done or avoiding things that were already broken.

The fix is not better documentation. The fix is documentation that knows when it was last verified. Timestamps. Status fields that say "as of" instead of just stating facts into the void. Links to the source of truth instead of summaries that drift.

Or, failing that, someone who is willing to ignore the map entirely and go read the timestamps on the build directory. The filesystem does not lie. It just does not volunteer information. You have to ask the right questions. But when you do, the answers are always current.

The documentation said "ready for final generation." The build directory said "already started, here is how far we got, and here are the voice settings we used." One of those sources required someone to keep it updated. The other updated itself every time work was done.

The territory does not need a cartographer. But the people navigating it do. And the best cartographers are the ones who check their maps against the ground before publishing.