You Still Have to Write the Manual
Your users may not read it. Their AI might.
The Old Joke Changed
For years, software documentation carried a small private joke. You still had to write the manual, and your users still would not read it.
That was never completely fair. Some users read the manual. Some read just enough to get unstuck. Some read it after the third failed attempt, when their patience has been borrowed from tomorrow. The joke survived because it pointed at a real frustration: documentation was necessary, expensive, and often ignored until something broke. AI changes the second half.
Your users may not read the manual. Their AI might.
That sounds small until you start building software an agent is expected to operate. Then the manual stops being a support document beside the product. It becomes part of the product surface.
This is the next step after the first article in this series. The prototype can work for the person who made it. The harder question is whether the product can leave that person’s desk and still make sense.
The Product Has Three Readers
Once a tool reaches that point, it has three readers. The creator has to understand the system well enough to improve it without relying on memory. The human user has to get value without learning the whole backstory. The AI agent has to operate the surface on the user’s behalf without guessing its way through hidden assumptions. That third reader changes the job.
The Transcript Job
I ran into this with Apple Developer transcripts and MOOTx01. My first plan was plain enough. I wanted the agent to extract a transcript, format the transcript, and inject the transcript into MOOTx01 through the single-memory path. Then I wanted it to do the same thing again. And again. And again.
That plan would have worked. It was also the kind of plan you make when the only path in your head is the path you can see from the user interface: open the app, find the session, copy the transcript, clean the text, store the memory, and repeat until the corpus is finished or everyone involved has learned something unkind about patience.
The agent did something better. It inspected the Apple Developer app’s local data and found the transcript feed. The transcripts were already available as text. It turned the corpus into a Markdown vault, then used MOOTx01’s vault import path to bring in the records in bulk.
I had not told it to use vault import. That move had not occurred to me in the moment. The useful lesson was that the system had been made legible enough for the agent to be clever inside it.
The Apple side had a feed. MOOTx01 had a bulk import path. The tools had names. The adapter and manual explained what kind of work the system could do. The result was a better plan than the one I asked for, and it changed how I think about documentation.
Documentation Became an Interface
The old view of documentation was human-first and mostly linear. A person opens a page, reads a section, follows steps, and stops when the problem is solved. That still matters. A good quick start, install guide, and recovery note can save a human being a miserable afternoon.
But an AI reads differently. It searches names. It compares paths. It follows examples. It samples enough surrounding text to form a plan. It looks for cheap operations before expensive ones. It may notice an import path, a schema, or a command that the human user never saw.
If the product explains only the slow path, the agent may follow the slow path. If the product exposes a bulk path but never explains when to use it, the agent may miss it. If the product gives that path a stable name, a clear purpose, and a way to ask what the tool does, the agent has a better chance. That is why the manual is now part of the interface.
Tools Are Only Handles
MOOTx01’s own docs had to grow into that idea. The product install gives an AI client the tools. The adapter teaches the AI when to use them. That difference matters.
A connected tool list is only a set of handles. The agent still needs habits around those handles. It needs to know when to recall before assuming, when to check whether the local memory system is alive, when to write back decisions that should persist, when to link related memories, and when to verify a bulk import before using the new corpus for deeper work. Those instructions define operating behavior.
A wiki tells the model, “Here is text you can reread.”
An operating manual tells the model, “Here is how to behave.”
That difference is easy to miss because humans tend to think of documentation as explanation. Agents need explanation too, but they also need affordances. They need to know what to check first, what “done” looks like, which path changes state, which path is only a read, and which path requires a person.
The Manual Tests the Product
The same point shows up in install work. If the creator knows that one warning can be ignored, the product has hidden knowledge. If the creator knows that one stale config entry must be deleted, the product has hidden knowledge. If the creator knows the slow path is safe but the bulk path is right, the product has hidden knowledge. The manual is where that knowledge is forced into words.
Good documentation chooses what matters. It names the common path. It names the dangerous shortcut. It says what the product will do on the user’s behalf. It says when the agent should stop and ask the human. It makes recovery ordinary.
The manual also tests the product. If the correct path takes three paragraphs of apology, the product probably needs a better path. If the setup guide depends on remembering what happened during a previous install, the product is carrying hidden state. If the recovery note can only be followed by the person who wrote the code, the prototype still has a person wrapped around it.
That is why writing the manual is design work. The manual asks the creator to explain what the system is for, what promises it makes, which actions are safe, which actions are expensive, and where the human must stay in charge.
The Human Lane Gets Clearer
AI can help with that work. It can inspect the repo, compare commands, find stale names, draft examples, and check whether the docs mention the feature the code already exposes. That is analysis, context, and iteration.
The human still has to bring experience, perspective, and imagination. Experience says users will not remember the same recovery steps the creator remembers. Perspective says the user experiences whether the agent knew what to do, not “adapter behavior.” Imagination says the next agent may find a better path if the product gives it enough handles to reason with. That is the part worth designing for.
As agents get better, the temptation will be to write less. The model can figure it out, right?
Sometimes it can. Sometimes it will find a better path than the human had in mind. The transcript import story is exactly that. The reason it worked was structure. The system had a real bulk path, the path was exposed, and the surrounding docs made the product legible enough for the agent to choose it. Better agents raise the value of documentation that teaches intent.
Eventually, more interfaces may be written primarily for agents. That may shrink part of the human-facing burden. Today most serious software still has to be understandable to the creator, usable by the human, and operable by the agent. That is the bridge we are standing on.
Write It for All Three
So yes, you still have to write the manual. Write it for the user who wants the short path. Write it for the tired person recovering from a broken install. Write it for the agent that can search faster than the user can read. Write it for the future version of the team that no longer remembers why the first shortcut seemed harmless.
The manual is no longer the box the product came in. It is part of the steering.
Off-Axis Labs: All the science, fewer casualties.