8th September, 2026 - We’re hiring for a project writer! Click here to find out more.
If we want to teach someone how to build an AI agent with a new framework, its technical docs give us a map of how it works - installation, models, agents, tools, memory, configuration and deployment… the list goes on. Technical docs now even include explanations and code examples, so the job of writing a project can look like simply turning that material into a simpler sequence of steps that a beginner can follow.
The result of doing that can be technically excellent and still be a poor learning experience. The problem is not that the technical docs are badly written. It is that technical docs and projects do different jobs. Technical docs are organised by feature i.e. what each part is and how to use it. A project has to be organised by learning order i.e. what a beginner needs to encounter, and when, to understand it.
Take memory in an AI agent framework. The framework’s technical docs need a section explaining what memory is, how to configure it, which options are available and how those options behave. Someone arriving at that page probably already knows that memory is the thing they need. A beginner following a project may not know why an agent needs memory at all.
Instead of explaining memory upfront, let the learner build without it: tell the agent something, keep talking, watch it forget. Memory then solves a problem they’ve actually hit - not just the next concept in the framework.
The technical material has barely changed, but the order has. That difference is one of the harder parts of writing a good project because the natural structure of the technology is often not the natural structure of learning it.
This changes the question a project writer is trying to answer. “What should I explain next?” tends to produce a sequence of explanations. “What does the learner need to encounter next?” can produce a very different sequence - the learner would instead see an output, make a prediction, encounter a limitation, compare two results, or watch something fail.
AI makes this distinction particularly important. An LLM can already take the technical docs for a framework and produce a convincing beginner tutorial from them. It can extract the important features, simplify the explanations, generate the code, put everything into a logical order and add troubleshooting for the obvious failure cases. As that gets better, the ability to produce tutorial-shaped content becomes much less valuable on its own.
The harder work is deciding that the logical order presented by the technology is wrong for learning it. Perhaps the learner should use the agent before learning about tools, encounter the memory problem before configuring memory, or leave one of the framework’s major features out entirely because it does not belong in this learning experience yet.
Those decisions are difficult to derive from technical docs because technical docs are not trying to answer the same question. A tool’s technical docs need to help someone understand and use the technology when they come looking for information. A tutorial has to decide what somebody should experience, and in what order, so that they develop an understanding they did not have before. The source material may be the same, but the structure should not be.
Happy learning,
p.s. We’re hiring for a project writer! Click here to find out more.