5 posts tagged with "Documentation"

Who are you actually writing for anymore? If half your readers are machines, and the open web is quietly shrinking as people move their questions into Claude and ChatGPT, the old instinct to "write for humans" starts to feel incomplete. A recent report from Mintlify, a documentation platform used by developer-focused companies to host and structure their API references and guides, forces the question into the open. Mintlify sits in a useful vantage point: because it powers so many developer docs sites, it can see exactly who, or what, is hitting those pages. Here are the three points from their report that matter most, and what I'm actually doing about each.

I have been thinking about this a lot recently.

We are in the middle of a wave of MCP server development. Teams across the industry are building connectors, tools, and integrations at pace, pushing them to GitHub, sharing them in developer communities, and expecting adoption to follow. Some of it does. But a lot of it does not, and when I look at why, the answer is almost always the same.

The documentation is not there.

Why I'm rebuilding how my team captures knowledge — and why an LLM is doing most of the work.

When Andrej Karpathy shared his approach to LLM-powered personal knowledge bases, something clicked. Not because the idea was entirely novel — knowledge management has been a cottage industry for decades, from Zettelkasten cards to Confluence wikis to Notion databases. What struck me was the specific inversion he described: the LLM doesn't just query your knowledge, it authors and maintains it. That distinction matters enormously, especially in fintech, where the gap between raw data and structured understanding is both large and expensive.

I've spent the last several weeks designing a version of this system for my own work — a knowledge base sitting at the intersection of payments infrastructure, regulatory compliance, and emerging AI tooling in financial services. Here's what I've found, what I'm building with, and why I think this approach genuinely outperforms every knowledge capture method I've used before.

Most teams shipping AI products in 2026 are focused on the model. Which one to use, how to fine-tune it, how to evaluate its outputs. What they are not focused on, almost universally, is the layer that connects the model to everything else.

That layer is the MCP server. And almost nobody is documenting it.

This is a problem. Not an inconvenience but a genuine technical risk, and in regulated industries, a compliance risk too. A developer joining a project finds an MCP server in the codebase with no tool reference, no input schema, no error documentation. The model is using it. Nobody knows exactly how. The person who built it left six months ago.

Technical Writing · Documentation · April 2026

Your docs are already being read by AI. The question is whether they're being read well — or whether a language model is piecing together a garbled summary from whatever it can scrape.

A few months ago I audited how several popular LLMs described our product's API. The results were humbling. Outdated endpoint names. Deprecated parameters presented as current. Hallucinated response shapes. The AI wasn't lying — it was doing its best with fragmented, unstructured context pulled from a dozen cached pages across our docs site.

The fix turned out to be surprisingly small: a single plain-text file called llms.txt, placed at the root of our documentation domain. Since adding it, AI-assisted developer support tickets citing our docs have become markedly more accurate. Here's everything I learned building it.