What’s the Point? (#23)
Contemplating the Real Value of Documentation
Last week, I grabbed dinner with a friend who works in product marketing for a tier-two manufacturing company. At some point, our conversation drifted toward work, and he asked me a question I’ve answered a hundred times before: “What’s the value of documentation?”
I launched into my standard response. “Documentation bridges the gap between a product and its user. It reduces friction, smooths onboarding, and cuts down on support tickets. Good docs anticipate questions and allow engineers and product managers to focus on higher-value work.”
He nodded politely but looked skeptical. After a pause, he said, “Yeah, I get what you’re saying. But if I were hiring a technical writer, none of that would really strike me. There’s something missing from your answer. Technical writing does something else, but I can’t place what it is.”
That comment stayed with me. What if my go-to explanation has been too narrow? What if the value of documentation isn’t simply functional, but something deeper?
The Explanatory Problem
Most of us in the field explain documentation by listing what it prevents: onboarding pain, endless support tickets, frustrated users. And it’s true — those are real benefits. But they sound defensive, as if documentation’s role is merely to minimize damage. It reduces churn, saves costs, and deflects complaints.
The problem with this framing is that it misses the affirmative value of documentation. If all we can say is that documentation prevents chaos, then we imply that its worth is only negative space, valuable only in the absence of problems. That answer will never inspire confidence, let alone investment.
This negative framing reminds me of another conversation I recently had with a family member. She described friendship in a bizarre way: “Friends keep you from being lonely. They give you someone to talk to when you’re down.” True enough, but inadequate. Friendship is not simply the absence of loneliness. At its best, friendship is formative. It shapes us into who we become.
In the same way, documentation is not just an absence of confusion. At its best, it is formative. It shapes how users see the product, how they experience its purpose, and even how they imagine what they can do with it.
Defining Terms
Let’s pause to name two ideas that will frame the rest of this discussion:
Utility value: The functional role of documentation in reducing friction, answering questions, and preventing problems.
Formative value: The deeper role of documentation in shaping perception, guiding imagination, and cultivating confidence in both product and user.
Both matter. But only the second explains why documentation deserves more than a grudging budget line.
Documentation and Self-Imagination
I believe the missing piece my friend was searching for is this: documentation doesn’t just tell people how to use a product. It shapes how they imagine themselves using it. In that sense, documentation has formative value.
When a user encounters a well-crafted guide, he doesn’t just learn how to click the right buttons. He feels oriented. He begins to believe the product can solve his problem and that he is capable of solving it. Documentation, then, is less about friction reduction and more about identity formation. It tells the user: you belong here, and this tool belongs with you.
Cognitive science lends support to this claim. In their 2003 study, Mayer and Moreno show that meaningful learning happens when new information connects to a practical goal and when users see how each step fits into a larger whole. Without this scaffolding, knowledge remains fragmented and is quickly discarded.
Good documentation provides the scaffolding. It doesn’t just prevent confusion. It builds confidence by connecting knowledge to action. In doing so, it shifts the user’s posture from hesitant outsider to capable participant.
Writing Formatively
So how can writers elevate their work beyond utility value and into formative value? A few practices stand out:
Begin with purpose. Every article should start by naming what the user will gain, not just what buttons they will press. Frame the task in terms of meaningful outcomes.
Connect steps to identity. Instead of writing “toggle this switch,” explain how the action enables the user to become more effective, secure, or creative.
Echo the product’s value proposition. Good documentation draws a through line back to the promises made in product marketing, helping users see that the value that sold them on the product continues to unfold as they use it.
Guide, don’t instruct. Good documentation feels like a knowledgeable companion walking beside the user, not a detached checklist. Anticipate confusion and speak with empathy.
Show the bigger picture. Remind the user how each piece of knowledge fits into a larger workflow or goal. Context breeds confidence.
Closing
As our dinner plates were cleared, my friend’s question lingered: What’s the real value of documentation? At the time, I stumbled through an answer about onboarding and support tickets. But I wish I had said this:
Documentation is not only a tool for reducing confusion. It is a practice of formation. It helps users imagine themselves as competent, capable, and ready to create. Its value lies not just in what it prevents, but in what it makes possible.
The real value of documentation is that it gives shape to confidence. Like friendship, it doesn’t just keep us from failing. It makes us more fully who we are meant to be.