A developer spent days writing comprehensive documentation.
No one read it.
The senior developer asked, “If documentation exists but is never consumed, what does it document?”
The developer replied, “The system’s behavior.”
The senior nodded, “And whose understanding does it reflect—the system’s or yours?”
Reflections
This koan challenges us to examine the true purpose of documentation. We often approach documentation as a technical artifact, a complete and accurate description of how our systems work. We measure its quality by comprehensiveness, accuracy, and detail. But the senior developer’s questions reveal a deeper truth: documentation exists not to describe systems, but to serve people.
When documentation sits unread, it becomes a monument to the author’s understanding rather than a bridge to others’ comprehension. The developer’s answer, “The system’s behavior,” is technically correct but misses the point entirely. Documentation that perfectly captures system behavior but fails to connect with its intended audience has documented only one thing: the gap between the writer’s mental model and the reader’s needs.
The senior developer’s final question cuts to the heart of the matter. Our documentation inevitably reflects our own perspective, our assumptions about what others need to know, and our preferred ways of organizing information. When we write for an imagined audience rather than real users, we create documentation that serves our need to have documented rather than others’ need to understand.
The koan invites us to shift our focus from completeness to usefulness, from technical accuracy to genuine communication. The most valuable documentation is not the most thorough, but the most accessible. It meets people where they are, answers the questions they actually have, and appears in the moment they need it. Sometimes that’s a comprehensive guide. Often, it’s something far simpler.
What matters is not whether we have documented, but whether we have truly communicated. The question is not “Is this complete?” but “Will this help?” When we approach documentation as an act of service rather than a technical deliverable, we create resources that people actually use, because they were designed with real humans in mind from the very beginning.