Machines are reading too.
Documentation has two audiences. This website is my experiment in writing for people and machines from the same source.
This website has two audiences. One is people who want to learn about me, my projects and my convictions. The other is machines: coding agents and AI assistants that actually read and evaluate pages, rules and relationships — not just index them. That is why the site is built for more than the browser.
Two surfaces, one source
For machines, the site maintains two complementary files. llms.txt is a convention that gives a website a short, machine-readable summary; my llms.txt is generated automatically from the same content people read on the pages. The AGENTS.md in the repository explains the project's rules to any coding agent: that the llms.txt must never expose unpublished content, that external links open in a new tab, and where the rules of the framework version in use live. Part of that file is even written by the framework itself — it regenerates on every dev start.
The decisive point: there is no second truth. People read pages, machines read structure. Both come from the same source files.
Writing for machines sharpens writing for people
The biggest effect of the experiment is a side effect. If an agent can misread my structure, a person without prior knowledge probably can too. A summary that fits in one sentence forces me to find the core. Stable addresses, clear names and unambiguous rules help both audiences at once.
The reverse also holds: what is understandable only to machines eventually becomes incomprehensible to people as well. Search engine optimisation demonstrated that years ago, when pages were written for crawlers and people were expected to put up with the rest. That is why I generate the machine version from the real content — not the other way round.
Principles
The experiment has given me a few principles:
- One source, two readings: the machine version is generated from the content people read — never maintained in parallel.
- Structure before style: stable addresses, short summaries and unambiguous names matter more than any design.
- Rules belong in the repository: an AGENTS.md replaces verbal handovers and knowledge that exists only in heads.
- Misunderstandings are tests: where an agent can misread, the ambiguity usually lies with the author — not the reader.
Machines are reading too. That does not make good writing easier — it makes it more important.