Write Only What Your Reader Cannot Find
Who reads your docs? An AI agent is a reader too. Write only what your reader cannot easily find, and link to the rest, so each reader gets what they need.
I opened my talk with one question: “Who actually read the last doc that you wrote?”
The room went quiet. Only the right reader makes a doc useful. Every other rule in this series starts from that.
How a memory system remembers
TencentDB Agent Memory keeps memory in four layers. It turns raw chat into short facts, and then into bigger patterns.
Lower layers keep the evidence. Upper layers keep the structure. People work the same way. Years of work turn into things that you “just know”. You do not need to write that layer down.
Each reader starts from a different base
| Reader | Already knows: skip | Only we know: write it |
|---|---|---|
| Senior engineer | clean code, design patterns, git, HTTP | why the service exists, flows across repos, past decisions |
| New team member | general computer science | company terms, where to start |
| PM and business roles | the industry and the product | what a feature does, its limits, who owns it |
| AI agent | what it learned in training | repo commands, decisions that live only in chat or in heads |
The AI era added a new reader. An AI agent reads fast. But it cannot read your team chat threads (Slack, Teams), and it cannot read the reasons in your head. Those are the things that you must write.
The rule: write only what your reader cannot easily find
The study group put it this way. If it is easy to find, link to it. If it is hard to find, write it out.
The answer changes with the reader. An engineer can read the code, but a PM cannot. So for the same fact, you link for the engineer and you write it out for the PM.
Each reader also looks in a different place. Engineers and AI agents read repo docs. New team members and PMs read the team wiki (Notion, Obsidian, Confluence).
A good name can save the reader from reading a doc at all. See A Good Name Is a Doc You Never Write.
First ask who will read it. Then decide how much to write.
References
Related: see how a good name replaces a doc, read Remember Where, Not What, or go back to the series overview: Docs in the AI Era.