Week 7 · the fifth dimension

Documentation: writing so machines understand you

The outcome dimensions were what AI says about you. The machinery dimensions are how you change it — starting with the words a model actually reads.

Makefield · Berlin

Crossing over

From what AI says to how you change it

The first four dimensions described the outcome — whether AI recognises you, describes you accurately, frames you fairly, and recommends you. The next three are the machinery underneath: the things you actually work on to move that outcome. The first piece of machinery is the most direct, because it's the part you fully control — your own documentation, the words a model reads when it tries to describe you.

Machines don't read like people

Chunked, extracted, summarised

An LLM doesn't read your product page the way a person skims it. It breaks text into chunks, pulls out entities and claims, and builds a summary from those pieces — as we saw in how AI answers are built. That changes what "good content" means. Prose written to persuade a human — long narrative paragraphs, assumed context, marketing language — often produces a vague or wrong AI summary, because the model can't cleanly extract the specific facts it needs. Content written to be retrieved produces accurate ones.

What good looks like

Facts a model can lift cleanly

Documentation that an AI handles well tends to share a shape: every key page states plainly what the product is and who it's for; specific claims — a price tier, an integration, a differentiator — are written as explicit, self-contained statements rather than buried in a paragraph; and common questions are answered directly, in the words a buyer would use. The test is simple: take three to five specific facts about you and check whether the AI can retrieve each one accurately. If it returns a generic summary instead of the fact, the documentation isn't extractable yet.

What failure looks like

The brochure problem

The common failure is documentation optimised for skimming, not retrieval: narrative marketing copy, key facts implied rather than stated, no direct question-and-answer anywhere. The symptom is an AI description of you that's generic — essentially the same one it would write for any competitor in your category — or one that quietly carries an outdated or wrong fact it couldn't correct because the right fact was never cleanly stated.

Why start here

The cheapest lever you control

Documentation is where machinery work should start, for one reason: it's the only part of this entirely in your hands. You don't control what Reddit says about you or which sources an engine trusts — but you fully control whether your own pages state your facts in a form a model can lift. It's the cheapest, fastest correction available, and it's the foundation the next two dimensions build on.

Next — Structured data: making your facts machine-true with schema, and why schema alone isn't enough. New here? Start with the overview.

Common questions

Questions this lesson answers

How should I write my website so AI understands my business?

Write it to be retrieved, not skimmed. A model breaks your pages into chunks, pulls out entities and claims, and builds its summary from those pieces, so the facts have to survive being lifted out of context. In practice that means every key page states plainly what the product is and who it's for; specific claims — a price tier, an integration, a differentiator — are written as explicit, self-contained statements rather than implied inside a paragraph; and common questions are answered directly, in the words a buyer would actually use. Prose written to persuade a person often produces a vague AI summary for exactly this reason.

Why does AI describe my company in a generic way that fits any competitor?

That is usually the brochure problem: documentation optimised for skimming rather than retrieval. If the key facts are implied by narrative marketing copy instead of stated, and nothing on the site answers a buyer's question directly, the model has nothing specific to lift — so it falls back on a category-level description that would fit anyone in your space. The same gap is how an outdated or wrong fact survives: the correct fact was never cleanly stated anywhere it could be retrieved.

How do I check whether my content is extractable by AI?

Take three to five specific facts about your business and ask the AI for each one. If it returns the fact accurately, that part of your documentation is extractable. If it returns a generic summary instead, it isn't yet — and you have found the exact page to rewrite. It is worth doing this per engine and more than once, since the same question does not always get the same answer.

Is documentation the same as adding schema markup?

No — they are two different dimensions, and documentation comes first. Documentation is the prose a model reads: whether your facts are stated in a form that can be lifted cleanly. Schema is the structured, machine-readable layer on top of it, which Week 8 covers, including why schema alone is not enough. Marking up a page whose facts are vague does not make them specific. Documentation is also the cheapest lever available, because unlike what third-party sources say about you, it is entirely in your hands.