How Not to Build Documentation: The Tale of an HTML Parser
How we tried to outsmart Doxygen, adapt its markup to our standards, and why it led us to build our own engine.
Building Flude
How Flude grew out of a throwaway script into an independent documentation engine -- one architectural mistake per episode.
Programming Without Knowing the Language: How AI Fired Doxygen
How we tried to parse XML, why AI suddenly pulled in tree-sitter, and why control is more important than genius code.
TDD as a Leash for AI: Writing Tests Without Knowing the Language
Why it's easier to rewrite AI code from scratch, how tests became our contract, and how to force the neural network to write its own checks.
The Markdown Singularity: Why Generating HTML is a Dead End
How a single question from our Infrastructure Lead forced us to rewrite our documentation pipeline, abandon HTML, and accidentally create Flude.
Guerrilla DevOps: How We Escaped to GitHub Actions
Corporate infrastructure, colleagues on vacation, and slow tools forced us to build an independent CI/CD pipeline. Here's how AI helped me master YAML in a few evenings.
Regression Testing: Proving Your Code Doesn't Lose Data
Writing a fast documentation generator is fun. Legalizing it in a hardcore enterprise environment is another story. Here's how we proved Flude's reliability by putting it head-to-head with the old standard.
Developer Guides: We didn't abandon the guides, just Flude—and then changed our minds
Dead cross-references between handwritten guides and auto-generated API pages quickly explained why managing guides away from Flude, as plain Markdown, was a mistake.
Typed Models: How we stopped silently losing data
The old universal model stored data as shapeless strings, leading to silent information loss. We rewrote the core with strict types, replacing silent degradation with loud validation errors.
The 'if not 0:' Easter Egg: How Our AI Audit Found Dead Code in the Orchestrator
No production outages or late-night drama, just a funny and revealing discovery. We ran an autonomous AI audit on our core engine and found a condition that was always, guaranteed, true.
Breaking Down Our Pipeline: From a Symlink Hack to Five Independent Deployments
How we untangled a five-project monorepo in one go, and the hard lesson a single Cloudflare token taught us.
Flude.guide: The Name We Had to Find Between Udemy, a Debugger, and nude.com
The working title was blocked by a registered debugger trademark. We hunted down a short replacement containing the ude substring while simultaneously evaluating sound, SEO potential, and legal safety.
The Illusion of Speed: A Two-Level Cache Can't Speed Up What Doxygen Can't Skip
Every rebuild used to run Doxygen and parse its XML from scratch, even when nothing had changed. Our two-level cache fixed that pain. But the title has a catch: the cache can't make things genuinely fast, because it only knows how to skip work that can be avoided altogether.
The Leak That Won't Die: How We Broke Python's tempfile
Victory over the old Doxygen parser turned into a new catastrophe. Temporary directories flooded the disk, and our 'fix' using garbage collection just made things worse.
The Phantom That Wasn't There: How Unreliable grep Made Us Chase Ghosts
What do you do when your parser generates documentation for a class that a global text search across the entire repository can't find? The story of one false panic.