Writing about writing
Essays on documentation drift, AI-assisted authoring, and keeping product docs in sync with the code behind them.
Measurable documentation for the agent era
Documentation is increasingly read — and acted on — by AI agents, while coding agents ship product changes faster than any team can hand-maintain docs. Accuracy and coverage stop being nice-to-haves and become measurable requirements. How Git2Docs measures documentation against your shipped code via an MCP validation loop that converges to zero findings in an hour — and how repo-health signals let your own coding agent raise fidelity over time.
Connecting your docs to AI agents: MCP, llms.txt, and Markdown
The reader of your documentation is increasingly a coding agent, not a person browsing a page. What that means in practice — MCP servers, llms.txt, and Markdown content negotiation — how to expose your docs to Cursor, Claude Code, and ChatGPT, and why the hard part isn’t the plumbing but keeping the content true enough for an agent to trust.
The hidden cost of documentation debt
Documentation debt never triggers an incident, so it never makes the roadmap — yet it quietly taxes onboarding, support, and refactoring, and turns a departing engineer into a knowledge cliff. How to make it visible and budget for it the way engineering teams already handle technical debt.
The GitBook migration trap
The obvious way to migrate off GitBook — export every page and import it verbatim — quietly forklifts the drift you were trying to escape, and leaves frozen islands in an otherwise self-updating site. A better migration treats the old docs as a seed, regenerates from the code, and measures topic coverage so you can prove nothing important was lost.
How AI can leverage documentation to provide excellent L1 and L2 customer support
Most AI support deployments underperform not because the model is inadequate, but because the documentation it draws on is. How documentation quality directly determines AI support quality across L1 and L2 — and the architecture that keeps an AI knowledge base accurate by syncing it to your codebase.
Why documentation falls behind code (and how to fix it)
The drift between code and docs is a structural problem, not a discipline problem. Three patterns that close the gap by treating documentation the way teams already treat tests, lints, and CI — enforced at the pull-request level, not left to memory.