Changelog
What changed and when.
New Blog Post: The Cascade: How One Wrong Field Name Crippled an AI-Powered Workflow
"The Cascade: How One Wrong Field Name Crippled an AI-Powered Workflow" — covers the cascade failure pattern where a single stale documentation field multiplies across every AI consumer. Explains the multiplier effect (1 error × 5 AI agents × 50 outputs = 250 daily instances), why documentation bugs in AI-native workflows look like unrelated incidents, and what to do tomorrow: drift detection, AI consumer inventory, and an accuracy target.
New Blog Post: ReadMe Has an AI Linter Now. It's Solving the Wrong Problem.
"ReadMe Has an AI Linter Now. It's Solving the Wrong Problem." — covers ReadMe's AI Linter, Mintlify's Agent Score, and why the entire documentation platform industry is measuring structural quality instead of accuracy. Explains the difference between writing tools and validation infrastructure, how MCP amplifies the accuracy problem, and what true doc validation looks like.
New Blog Post: Vibe Coding Makes Your Docs the Only Truth Left
"Vibe Coding Makes Your Docs the Only Truth Left" — explores how AI-generated code (Lovable, Bolt, Cursor, v0) is making code ephemeral and documentation the only persistent artifact in codebases. Covers the inversion of the code-truth relationship, why docs weren't built to be the permanent layer, the math of drift at scale, and why continuous validation becomes critical when code changes every sprint.
New Blog Post: How to Write OpenAPI Specs That Don't Lie to AI Agents
"How to Write OpenAPI Specs That Don't Lie to AI Agents" — a practical guide to writing OpenAPI specs that both humans and AI agents can trust. Covers the five lies OpenAPI specs tell (type mismatches, phantom parameters, undocumented errors, fake constraints, and silent defaults), why AI agents make spec accuracy a production reliability concern, and a continuous validation loop for keeping specs honest.
New Blog Post: Your Documentation Retrieval Quality Is Broken
"Your Documentation Retrieval Quality Is Broken. Here's How to Fix It." — explores the invisible problem of documentation retrieval quality: why accurate docs can still produce wrong agent behavior when the structure defeats retrieval. Covers the three structural problems (mixed topics, implicit context, wrong page boundaries), patterns for retrieval-aware docs (one concept per page, front-loaded context, machine-readable markers, page classification), and how boringdocs validates retrieval structure.
New Blog Post: Your Documentation Is a Dependency Graph
"Your Documentation Is a Dependency Graph. Act Like It." — explores how documentation has an implicit dependency structure (code → API docs → tutorials → MCP servers → AI-generated code), why it's deeper than code dependency graphs, and what dependency-aware documentation looks like: explicit mapping, critical path testing, version coupling, and upstream change alerts.
New Blog Post: Your Documentation Should Be a Deploy Gate
Published "Your Documentation Should Be a Deploy Gate" — a practical guide to making documentation accuracy a CI/CD gate that blocks bad deploys. Covers the three levels of documentation enforcement (coverage, accuracy, quality), why AI agents make deploy gates more critical, and how to start with a simple coverage gate today.
New Blog Post: Treat Documentation Accuracy Like an SLO
"Treat Documentation Accuracy Like an SLO" — a practical framework for defining documentation accuracy targets the same way engineering teams define uptime SLOs. Covers the documentation error budget concept, why AI agents make doc accuracy a production reliability concern, and a four-step framework for implementing doc accuracy SLOs in practice.
New Blog Post: Your Documentation Is a Product Surface
"Your Documentation Is a Product Surface. Treat It Like One." — argues that documentation isn't internal content but a product surface that humans and AI agents interact with. Covers the 7.5% design token accuracy stat, why "docs as content" breaks down, and what treating docs as a surface changes.
New Blog Post: The Marginal Cost of a Documentation Error Went to Zero
"The Marginal Cost of a Documentation Error Went to Zero — And That's a Problem" — explores how AI coding assistants propagate doc errors at machine speed, why the economics of documentation changed, and what teams can do about it.
New Blog Post: The Documentation Metrics That Actually Matter
"The Documentation Metrics That Actually Matter" — breaks down which documentation metrics are vanity metrics vs. which ones actually predict whether your docs are working, with a focus on accuracy over coverage.
New Blog Post: Your Documentation Debt Just Became Expensive
"Your Documentation Debt Just Became Expensive" — exploring how documentation debt compounds like technical debt, why AI agents changed the interest rate overnight, and why the cost of stale docs went from tolerable to unbearable. Includes the new "AI agent tax" framework for understanding how bad docs multiply costs at machine speed.
New Blog Post: "Docs as Code" Is the Wrong Abstraction
"Docs as Code" Is the Wrong Abstraction" — argues that docs-as-code solves versioning but not accuracy, why the AI era demands a validation-first approach, and introduces the docs-as-validation alternative with a concrete workflow comparison.
New Blog Post: llms.txt — The Standard Your Documentation Is Missing
"llms.txt: The Standard Your Documentation Is Missing" — exploring the new web standard for making documentation machine-readable, why it exists as a band-aid for a deeper problem, and why navigation without accuracy is incomplete.
New Blog Posts: AI Agents Don't Skip the Boring Parts & API Docs for Machines
"AI Agents Don't Skip the Boring Parts" and "Your API Docs Have Two Audiences. They Need Different Things." — two companion pieces exploring how AI agents read documentation differently than humans.
New Blog Post: Documentation Is Becoming a Contract
"Documentation Is Becoming a Contract (Not a Reference)" — exploring how AI agents read API docs as executable contracts, what happens when the contract is wrong, and why doc accuracy has become a reliability concern.
New Blog Post: Why Docs Platforms Can't Save You
"Why Your Documentation Platform Can't Save You" — a deep dive into why Mintlify, ReadMe, GitBook, and other docs platforms solve the wrong problem (presentation instead of accuracy), and why the industry needs a validation layer.
New Blog Post: Documentation as AI Training Data
"Your Documentation Is Training Data for AI Agents" — exploring how AI coding assistants consume documentation, why accuracy standards have changed, and why MCP makes doc accuracy more important than ever.
New Blog Post: Measuring Documentation Drift Cost
"The Hidden Cost of Documentation Drift" — a framework for calculating what bad docs actually cost in support, onboarding, lost adoption, and engineering time.
AstroDeck Rebuild
Rebuilt the entire site on AstroDeck template. New design system with Tailwind CSS v4, dark/light theme toggle, skin switcher, and responsive layout. Added docs section, contact page, and video dropdown in nav.
Features & About Pages
Added /features and /about pages. Features page uses AstroDeck sections (Features, Stats, FAQ, CTA). About page uses card-based layout with stats.
Migration to Vercel
Migrated from VPS to Vercel. Static output. Custom domain boringdocs.com. Deployed via git push.
Skin System Fixes
Fixed button text contrast in dark mode (default skin), terminal skin, and cold skin. All skins now have proper contrast ratios.
Initial Launch
boringdocs goes live. Static site with blog, 5 skins, privacy policy, terms, and email waitlist. Built with Astro.