Ivan Walsh

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.

When your organisation deploys an AI model, who is responsible for explaining what it does, what it should not do, and what happens when it gets something wrong?

If the answer is "nobody," that is a problem. And it is a problem that is landing, increasingly, on the desks of technical writers.

AI models are being built and deployed at a pace that has outrun their documentation. Teams can tell you how a model performs on a benchmark. They are far less prepared to explain its training data, its known failure modes, or whether it has been tested against the populations it will actually affect. That gap is closing, slowly, under pressure from regulators, enterprise procurement teams, and the growing expectation of transparency around AI systems.

The document that closes that gap has a name: a model card.

If you have not encountered one yet, you will. This article explains what model cards are, why they matter, and what you need to know to start writing one.

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.

AI isn't coming for your job.

It's coming for the tasks that make up your job.

This isn’t a new story.

If you’ve ever read a James Bond novel, you’ll remember the typing pool. Highly trained typists who could type super-fast and send confidential reports to the four corners of the world to stymie the latest villain. You don’t see too many typing tools any more. When the typewriter arrived, the typing pool as we knew vanished.

When we're in the role of a 'reader' we tend to skim over the 'happy path' in user guides and other types of documentation. Quite often we only turn to documentation when lost, confused, or uncertain. For instance, someone changed a parameter setting and we can't figure out how to fix it. So, we crack open the docs, search, and go hunting for the answer. But where is it? What should I search for?

I mention this as last week, I started to listen to Roger Penrose's 'The Emperor's New Mind' and came across a section where he discusses 'truth tables' in the context of classical logic and computation, and also their limitations in terms of understanding 'human' consciousness.

On the way home from my walk, I began to think if I could apply this concept to technical documentation.

How can technical writers use Agile in software development projects?​

As this question, and variations of it, have popped up on Reddit and LinkedIn, I thought I'd share a few observations about my experience of working with Agile/Scrum as a tech writer.

One thing to say before we start, is that just became a company says it's Agile, doesn't mean it's applying all of the framework. Rather, they may be selectively picking pieces of it, such as using Daily Stand Ups, but not fully embracing the spirit of Agile development. In many cases, they're probably 'Agilefall' (Agile + Waterfall).

What's the best tool for managing technical documentation websites?

You've probably seen something like this on LinkedIn or Reddit. And the answer is, as always, 'it depends'.

For example, this site is run on Docusaurus, which is pretty easy to setup and maintain. It also works very nicely with Git and our web hosting provider, so for a relatively simple site, it's fine. I should add that you can Docusaurus is not just for lightweight document sites as it has quite a lot of rich features, themes, and a very active community. So, worth a peek if you're looking to get started.

However, there are a few things it doesn't offer. At least, not out of the box. This leads us to Antora.