The problem with documentation
Here's what usually happens: You're trying to fix something at 2 AM. You find the docs. They start with a 10-minute explanation of architectural philosophy.
Or the opposite: You want to understand why something works the way it does, and the docs just throw commands at you. "Do this, then this, then this." No context. No reasoning.
After 40 years, I've seen this pattern everywhere. Documentation fails when it doesn't respect the reader's mental state. Are they learning? Are they working? Do they need to do something or understand something?
The problem isn't bad writing—it's mismatched intent. You can't serve someone who's trying to learn with docs written for someone who's trying to work, and vice versa.
The four states of mind
There's a framework called Diátaxis that gets this right. It maps documentation to four distinct mental states.
Think of it as a compass with two axes:
| Acquisition (learning) | Application (working) | |
|---|---|---|
| Action (doing) | Tutorials Learning by doing | How-To Guides Solving problems |
| Cognition (knowing) | Explanation Understanding context | Reference Looking up facts |
When someone's learning, they're either doing (tutorials) or understanding (explanation). When they're working, they're either doing (how-to guides) or knowing (reference).
Four quadrants. Four completely different needs. Mix them up and you create friction. Keep them separate and everything flows.
The Experience (Tutorials)
A tutorial is a lesson. You're the instructor, the reader is the student, and you're responsible for their success.
Think of a driving lesson. The goal isn't to get from A to B—it's to build skills and confidence. You don't explain traffic theory. You don't optimize the route. You just help them learn by doing, in a safe environment where they can't screw up too badly.
On this site, that's our Experience section. We walk you through creating your first digital installation, step by step. No assumptions, no shortcuts, just: "Do this. Now do this. See how that works?"
Tutorial rule: The student learns through what they do, not because you tried to teach them. Your job is to keep them moving forward and feeling capable.
The Process (How-To)
A how-to guide addresses a real-world problem. You assume the reader is competent and just needs directions.
"How to deploy to your own infrastructure." "How to configure HTTPS with your certificates." "How to troubleshoot connection issues." These are work documents. The reader isn't studying—they're trying to get something done so they can move on.
Our Process section is all how-to guides. We don't explain why you'd want to self-host (that's philosophy). We don't teach you networking fundamentals (that's a tutorial). We just show you how to solve the problem in front of you.
How-to guides are ruthlessly practical. Get in, solve the problem, get out.
The Craft (Reference)
Reference is just the facts. No opinions, no interpretation, no hand-holding.
API specifications. Configuration options. Command syntax. Method signatures. The stuff you look up when you know what you're doing but can't remember the exact parameter name.
Our Craft section is reference material. Technical specifications, API docs, configuration schemas. It's organized to mirror the structure of the thing it describes—just like a map reflects the territory.
Reference rule: Be accurate, complete, and neutral. Don't try to teach. Don't editorialize. Just give the reader what they need to use the thing correctly.
The Philosophy (Explanation)
Explanation provides context. It answers "why?" and connects things to a bigger picture.
This is where you can have opinions, take perspectives, circle around a topic from different angles. You're not teaching (tutorial) and you're not solving a problem (how-to). You're helping someone understand.
This page you're reading right now? It's an explanation. I'm not teaching you how to classify documentation (that would be a tutorial). I'm not showing you how to fix bad docs (that would be a how-to). I'm giving you context—helping you understand why this framework matters.
Our entire Philosophy section is explanations. Why we build custom instead of using proprietary solutions. Why self-hosted matters. Why dignity.ink is non-negotiable. The why behind everything.
Why this matters for bespoke work
Off-the-shelf documentation assumes one path, one use case, one way of thinking.
But bespoke installations are yours. You need to truly understand them. You need to be able to maintain them, extend them, troubleshoot them at 3 AM when nobody's around to help.
That means you need all four types of documentation. Tutorials to get started. How-to guides for common tasks. Reference for technical details. Explanation for understanding the design decisions.
We've proven this works at scale. Demostar.io—over 25,000 lines of code, 2,111 demos delivered, zero failures. Enterprise teams at companies like Zscaler trust it. That only works because the documentation respects how people actually learn and work.
Custom > Proprietary means users need to truly own the knowledge, not just rent access to it. Good documentation is how bespoke work survives after you walk away.
See it in practice
Want to see what Diátaxis looks like in the real world? Check out HomeStar's documentation.
HomeStar is a white-label real estate platform we built for brokerages and teams. The docs organize by role (Agents, Brokers, Admins) and by mental state—not by arbitrary categories.
Get Started
Tutorials that walk you through your first actions by role
Features
How-to guides for Scribe, semantic search, map search, alerts
API Reference
Technical specs for developers integrating with the platform
Role Overviews
Context and "why" for each user type's workflows
Same platform, same features—but organized around how people actually use docs. Agents learning the system start with tutorials. Agents working a deal jump to feature how-tos. Developers integrating go straight to reference. Everyone gets what they need when they need it.
Inside-out improvement
You don't need a perfect plan. You just need to start.
Look at your docs right now. Is there any way they could be improved? Even something small? Good. Do that one thing.
Maybe you move an explanation out of a tutorial. Maybe you add a how-to guide for a problem people keep asking about. Maybe you split a reference section that was trying to teach and document at the same time.
One fix at a time. See if it helps. Repeat. You'll find that each improvement gives you a clue about the next one.
"You can do just one thing, right now, and even if you do nothing else ever after, you will at least have made that one improvement."
— The Diátaxis philosophy
That's how all good work happens, honestly. Not grand plans. Just noticing what's broken and fixing it.
The compass tool
When you're writing or reviewing documentation, ask yourself two questions:
- Does this content inform action (doing) or inform cognition (knowing)?
- Does it serve acquisition of skill (learning) or application of skill (working)?
| If the content… | …and serves the user's… | …then it must belong to… |
|---|---|---|
| informs action | acquisition of skill | a tutorial |
| informs action | application of skill | a how-to guide |
| informs cognition | application of skill | reference |
| informs cognition | acquisition of skill | explanation |
That's it. Two questions, four answers, clear classification. Use this when you're stuck or when something feels off about a piece of documentation.
Further reading
Everything I've described here comes from Diátaxis, a framework created by Daniele Procida.
That site explained it first. We're just showing how it works in practice—how it shapes this entire website, from the Experience section (tutorials) to the Process guides (how-to) to the Craft specs (reference) to this Philosophy section (explanations).
Diátaxis is open. No license, no lock-in, no vendor. Just ideas that work. That's Custom > Proprietary in action—good frameworks don't need to be owned, they just need to be useful.
Attribution:
The Diátaxis framework was created by Daniele Procida. Companies like Gatsby, Cloudflare, and Vonage use it. It's proven, practical, and freely available.
