loading . . . Writing Docs for an AI I’ve been writing a lot of documentation for CSLA recently. Not for humans, but for AIs.
When I tell people I’m writing for an AI and not a human, they often ask “what’s the difference?” It’s a good question. After all, both AIs and humans read text. But there are some key differences in how they process information.
When writing for a human, you need to make certain assumptions about their background knowledge, and it is always better to assume less than more. I know I find it frustrating when I come to a document and the author has just assumed I’m already a Linux IT expert or that I know all about some niche tool.
Writing for a human means explaining every bit of jargon, expanding any acronyms, and providing context for any concepts that might not be universally known. You also need to consider the flow of the document, making sure it is engaging and easy to follow.
The flow or structure of a human-focused document is often more important than the content itself. You want to keep the reader engaged and interested in what you have to say. This means using storytelling techniques, such as anecdotes or examples, to illustrate your points and make them more relatable.
When writing for an AI, you can assume that it has access to a vast amount of information and can understand complex concepts without needing them to be explained in detail. An AI either knows, or can instantly look up, any term, acronym, or concept you mention. This means you can be more concise and to the point when writing for an AI. In fact, you _want_ to be concise, as the longer your document, the more of the LLM context window you will consume, and the more likely it is that the AI will forget important details from the beginning of the document by the time it gets to the end.
When writing for an AI, you also need to consider how it processes information. AIs are designed to analyze and understand text in a very different way than humans. They can quickly identify patterns and relationships between different pieces of information, and they can use that information to generate new insights or make predictions.
The flow or structure of a document for an AI is less important than the content itself. AIs are not easily distracted by tangents or irrelevant information, so you can focus on providing the necessary information in a clear and concise manner.
There are commonalities. Either way, you want to be clear and concise. Avoid unnecessary words or phrases that don’t add value to the document. Use simple language and avoid jargon whenever possible. And always proofread your work to ensure it is free of errors and easy to understand. This is true for human and AI consumers.
I think about the books I’ve written over the years, and just how much content was in each chapter to help guide the reader through the material. To explain concepts, jargon, acronyms, etc. More experienced readers, I’m sure, just skimmed over those sections, but they were indispensible for less experienced readers.
When I write documentation for an AI, I can skip all of that. I can just get to the point and provide the necessary information without worrying about whether the reader will understand it or not. The AI will either understand it or it won’t, but it won’t be confused by extraneous information. https://blog.lhotka.net/2026/01/11/Writing-Docs-For-An-Ai
