Rewriting the manual for its real readeressay
As HTML, my homelab manual weighed close to half a megabyte. Rebuilt as plain Markdown, the same knowledge comes to roughly 130KB. About 1 in 4 bytes was substance; the rest was presentation, rendered for nobody, because every piece of documentation is written for an imagined reader and mine was quite literally imaginary. Alexandria, the homelab manual from an earlier post, began life as a styled HTML site: hand-tuned CSS, a navigation sidebar on every chapter, little status dots, the whole thing browsable offline from a plain folder. I had built a pleasant reading experience for a human visitor who, an honest audit of history shows, almost never visited. When I consult Alexandria myself, it’s on GitHub, in thirty-second bursts. The reader that consumes it constantly, whole chapters at a sitting, is the AI that helps run the lab.
That reader has peculiar economics that humans do not: it pays by the token, markup included. Every time it consulted a chapter, it paid full price for angle brackets, duplicated sidebars, and styling directives that carry no information about my network whatsoever. And the waste wasn’t only financial. A model’s attention thins as its context fills with noise, a degradation now common enough to have earned a name, context rot; the same markup that cost me tokens was also burying the handful of facts about my network that the reader actually needed. Trimming the manual made it cheaper to read and, just as usefully, easier to read well. The two goals turn out to be the same goal.
The recent hardware migration was the forcing function. Alexandria had been framed as a migration runbook, and once the migration finished, its role changed: it needed to become what I’d been calling it all along, a living reference of the current state. My homelab bible. So it got the full overhaul in one pass: converted to Markdown and reorganized to follow the stack itself (physical platform, then services, then operations), with the migrations retired to appendices as history rather than deleted.
The risk in a bulk, AI-assisted conversion isn’t losing formatting; it’s corruption with confidence, a rewrite that quietly invents facts in fluent prose. I’ve been burnt by hallucinations before, so the conversion ran under fidelity rules. Convert, don’t invent: no new claims get asserted during a format change. Every chapter keeps its audit date. Anything uncertain gets an explicit verify marker instead of a confident sentence. Afterward, a live read-only audit walked the real systems and resolved the markers one by one. A hallucinated manual is worse than no manual, because it argues with you at exactly the moment you’re least equipped to argue back.
What the switch bought, beyond the token savings: GitHub renders Markdown, so the repository’s file tree is now the navigation, replacing sidebars that had been duplicated into every page by hand and drifted accordingly. Diffs became readable; a config change now shows as a two-line diff instead of a wall of markup. And there is no build step left to break. What was lost is the custom styling, and days in, nobody has missed it. Least of all the reader it was built for.
What the manual is for changed along the way, too. It started as insurance against my own forgetting; it has become operational substrate: the AI reads the relevant chapter before it touches the lab and updates the chapter after, and I audit the diffs instead of authoring the pages. Designing information for a machine reader is starting to get a name of its own, context engineering, and the surprise is how little of it is new. It comes down to the old virtues a good editor would recognize: say true things, say them once, keep them current, and cut the rest. One by one, the lab’s systems are converging on the same shape, plain text, versioned in git, legible to human and machine alike, and the manual just got there first. My personal knowledge base is next in line.