May 2026

Documention foundations for humans and AI

I’m on a mission to improve how I write documentation for both humans and AI.

As organisations rush to adopt AI, documentation suddenly needs to work for machines as well as humans. The nice part is we don’t need some magical new AI documentation framework that was invented by a startup with a logo that looks like a cat’s butt and a suspicious amount of venture capital. The same things that make documentation more accessible for people also make it easier for AI to understand.

With companies pouring money into the AI hype machine, this feels like a rare opportunity to quietly make documentation more accessible for everyone while nobody is paying attention.

Before I dig into different types of documentation, I want to think through three foundations that apply to almost everything we write:

Use plain language to reduce ambiguity

Plain language benefits humans

A shocking amount of writing in product and tech is unclear, overcomplicated or trying far too hard to sound clever.

People don’t read documentation carefully. They scan it while tired, distracted and already annoyed because something is unintuitive or unclear. 

Plain language increases the chances that people actually understand what you wrote.

Plain language means:

This sounds easy until you try doing it.

Writing plainly takes effort. You have to understand something properly before you can explain it simply. A lot of complicated writing is just confusion wearing a Patagonia gilet and pretending it has a strategy.

One of my favourite resources is the UK Government Digital Service content guidelines. Advice is practical and includes a helpful list of words to avoid.

If you want to measure readability, there are various scoring systems. One of the most common is the Flesch Reading Ease Score. It assigns a score to text between 1 and 100. The longer your sentences and the more complicated your words, the lower the score.

For example:

“Outputs generated by large language models may exhibit variability and should be validated against authoritative sources.”

That scores around 19, meaning it should be understandable to university graduates.

Meanwhile:

“AI can be wrong, so always check its answers against trusted sources.”

That scores around 76, meaning it should be understandable to a 12-year-old.

Unfortunately if you work in accessibility, you are permanently doomed to a terrible readability score because words like “accessibility”, “dyslexia” and “dyscalculia” apparently require a university education. I have words for whoever named these.

Plain language benefits machines

AI also loves unambiguous language.

Short, simple sentences make it easier for Large Language Models (LLMs) to parse content accurately and return sensible results.

The irony is that AI-generated writing tends to be stupidly verbose unless you force it not to be. We’ve somehow invented machines that can take one sentence and then immediately produce four paragraphs saying absolutely nothing.

Whenever I use a new AI tool or set up an agent, I load it up with instruction files to make sure the responses stay simple and clear. Uploading my own geri-style-guide.md, which defines my preferred tone, structure and plain language rules, means an LLM returns content in a style that doesn’t give me so much ick.

Structure: make documentation predictable

Structure benefits humans

Predictable structure reduces cognitive load.

When information is consistently organised, people build a mental model of where things live. They stop wasting energy hunting for information and start focusing on the actual task.

This applies at every level:

Structure for humans means:

If you want to improve accessibility, semantic structure is one of the best places to start.

Regions group related content. Headings describe the content below them. Lists support scanning and communicate hierarchy. These things help screen reader users, but they also help literally everyone else.

The W3C Web Accessibility Initiative has a useful tutorial on structure which explains the benefits clearly. This doesn’t just apply to HTML. Emails benefit from structure. Google Docs benefit from structure. Slack messages benefit from structure. Half the meetings I attend would benefit from a heading hierarchy and a skip link.

I wrote more about documentation structure in a previous post where I proposed a documentation framework for product and tech organisations.

Structure benefits machines

Machines are literal. If information is buried, inconsistent or vague, AI has to guess. Humans can usually recover from messy documentation because we use context and experience. Machines confidently hallucinate and present the answer like it’s fact.

Structure for machines means:

Structured docs make it easier for AI systems to retrieve, chunk and summarise content. This reduces hallucinations and creates clearer relationships between concepts. A sensible structure also helps AI understand not just what something is, but when to use it, how it behaves and what constraints apply.

If you work on a design system, you can’t expect agents to generate accurate layouts and flows if your documentation is disorganised. Agents are not going to magically produce clean code if your docs read like someone rage-typed them into Confluence during a production outage.

Accessibility: make documentation available to everyone

Accessibility in documentation is not just about screen readers and colour contrast. It also includes where documentation lives, how easily people can access it and whether the format can be understood by both humans and machines.

Digital accessibility

If you publish documentation digitally, follow established accessibility standards like the Web Content Accessibility Guidelines (WCAG).

WCAG is built around four principles that apply nicely to documentation:

Most documentation accessibility issues are not especially glamorous. They are usually things like:

The depressing thing is we’ve known how to fix these problems for years and we still keep shipping them anyway. If you think I’m exaggerating, check out the list of most common issues in the WebAim Million.

Docs should exist where people work

Accessibility is also about reducing friction. Every time someone has to context-switch, search a different website or ask someone for a link, the documentation becomes less accessible.

Good documentation should exist where people already work:

I don’t necessarily mean the docs should be written there. I mean they should be surfaced there. Once documentation becomes structured and machine-readable, it can appear through plugins, agents, AI assistants and tooling without duplicating content across multiple systems.

That’s when documentation starts behaving more like infrastructure.

Accessible formats benefit humans and machines

Your documentation format matters.

Source-readable formats like Markdown, AsciiDoc and reStructuredText work well because they are readable as plain text while still providing consistent structural markers for machines.

Humans like source-readable formats because:

Machines like them because:

This is one reason Markdown has quietly become the default format for technical documentation.

I’m a huge fan of Markdown. I’m writing this post in it.

The only annoying part is not being able to share unfinished drafts in the browser like you can with Google Docs. Matt Webb recently shared a lovely little tool called Mist, which acts like Google Docs for Markdown. I love small tools that solve one problem properly ❤️.

Try to avoid documentation trapped inside proprietary systems, platform-specific markup or formats that only work in one tool. Those systems might work for your team today, but source-readable formats give you a much better foundation for future tooling, automation and AI workflows.

Documentation is becoming shared infrastructure

Humans and machines are now reading the same docs and both are suffering when they’re a mess. If your underlying docs are a mess, AI output is ongoing to get progressively worse.

The reassuring thing is we don’t need some revolutionary AI methodology to fix this. We already know what good documentation looks like. The same things that help humans understand content also help machines retrieve, parse and reuse it. Accessibility practices turn out to be surprisingly good AI practices too.

So before we all sprint off to build autonomous AI agents that rewrite our codebase and order oat milk on our behalf, we should sort the foundations first. Everything else builds from there.

If you have opinions, hit me on Bluesky