Documentation is the Product (We just Pretend it Isn’t)

There’s a quiet truth in every technical organization: documentation is the product. Not the UI. Not the API. Not the architecture diagram. Documentation is the thing that determines whether people can actually use what we built.

But we rarely treat it that way. We treat documentation like a side quest. It’s something we’ll “get to later,” something that’s “nice to have,” something that exists to satisfy a checkbox rather than a user. And because of that, we end up with systems that are powerful, elegant, deeply engineered… and practically inaccessible.

This isn’t a new problem. It’s as old as technology itself.

This is an opportunity to rethink the way we approach product. If you’re like me (and you know who you are), the side quests are the best part of any game experience. We should prioritize them, not speedrun products out the door.

The Oldest Tradition in Tech: Obfuscation

If you zoom out far enough, you’ll notice a pattern: every generation of technology adds another layer of abstraction, and every layer hides something important.

• Microcode hid transistors
• Drivers hid hardware.
• Virtualization hid the O/S.
• Containerization hid processes.
• Orchestration hid containers.
• Serverless hid infrastructure.

We’ve been building walls around complexity for decades. Sometimes intentionally. Sometimes accidentally. But always in a way that makes the underlying system harder to see. This has always been in the name of making things simpler.

Want to find out $x^y$? You can write a binary function to multiply $x$ to itself $y$ times, but that requires a multiplication function. A multiplication function is an addition function where the number is added to itself $z$ times. So, we’re already getting two layers of obfuscation where [math]::Pow(2,10) is easier.

Engineers love these layers — they’re elegant, clever, and often necessary. But for the people who use the system, the layers don’t matter. I’m going to repeat that again, because that’s important: the layers don’t matter. They don’t need to know how the scheduler works, or how the hypervisor swaps memory pages, or how the container runtime isolates namespaces.

They need to know how to get something done.

And that’s where documentation becomes the product. It’s the only thing that makes the layers navigable.

The Real Purpose of Documentation

Documentation may start as a record of what the system does. but It’s actually a translation layer. It’s the bridge between the system’s internal logic and the user’s external goals.

Good documentation answers four questions (big props to Leon about the importance of four questions):

1. What is this?
   Not in marketing language — in human language.
2. Why does it matter?
   People don’t care about features; they care about outcomes.
3. How do I use it?
   Not theoretically — practically.
4. What happens when things go wrong?
   Because something always does.

When documentation answers these questions clearly, the system becomes usable. When it doesn’t, the system becomes a puzzle. As much as people enjoy spending their time on Wordle or Connections, they don’t want to waste time solving work-related puzzles – especially when the solutions are supposed to resolve puzzles.

The Cost of Pretending Documentation Isn’t the Product

When documentation is treated as an afterthought, the consequences ripple outward:

• Support tickets increase because users can’t self‑serve.
• Adoption slows because people can’t understand the value.
• Features go unused because no one knows they exist or why they exist.
• Engineering time gets wasted because teams re-explain the same value props repeatedly.
• Trust erodes because users feel lost.

The irony is that we often blame the system for these problems. “It’s too complicated.” “It’s too hard to onboard.” “It’s too confusing.”

But the system isn’t the problem. The lack of translation is.

Documentation as a Design Surface

If documentation is the product, then it deserves the same care as the product:

• Information architecture is UX.
• Examples are onboarding flows.
• Troubleshooting guides are support experiences.
• Conceptual overviews are product marketing.
• Diagrams are interface design.
• Glossaries are accessibility features.

Documentation is not a companion to the product. Documentation is the interface through which most people experience the product.

The code is for machines. The documentation is for humans.

The Layers Don’t Matter – The Story Does

Remember those layers — drivers, virtualization, containers, orchestration? They’re fascinating. They’re clever. They’re worth understanding if you’re building systems.

But most people aren’t building systems – they’re using them. And for them, the layers don’t matter. The story does. Documentation is where the story lives.

It’s where you explain everything: the actors, the flows, the feedback, the outcomes, the decision-making. Long story short, it’s the place to explain the “why” behind the “how.”

Documentation is the place where complexity becomes legible and a legible solution becomes a tangible one.

Documentation Creates Confidence

When documentation is clear, people feel confident. And confident users will explore on their own and make additional feature requests. They’ll self-serve because you’ve given them the troubleshooting know-how to allay panic. It encourages users to break outside their silos and think of other teams. When the documentation is good and tells a compelling story, they’ll adopt more features and teach others about the solution

Confidence is the force multiplier that makes systems successful. Documentation is the thing that empowers it all.

The Future Belongs to Teams Who Treat Documentation as a First-Class Product

The organizations that win aren’t the ones with the most features. They’re the ones with the clearest explanations.

Because clarity scales. Clarity reduces friction. Clarity accelerates adoption. Clarity builds trust. Clarity turns complexity into capabilities.

Documentation is the product. We just pretend it isn’t.

And the moment we stop pretending – the moment we treat documentation as the interface, the narrative, the onboarding, the support system, the translation layer – everything gets better.

Systems become usable. Users become confident. Teams become aligned. And complexity becomes something people can navigate, not something they fear.