written by Eric J. Ma on 2025-07-07 | tags: documentation diataxis innovation tutorials guides reference ai strategy product jobs theory
In this blog post, I explore how combining the Diataxis documentation framework with Clayton Christensen's jobs-to-be-done theory can transform the way we write docs. By focusing on the specific outcomes readers want to achieve, we can make our documentation more useful and competitive—not just against other docs, but against all the ways people solve their problems. What happens when you treat your documentation as a product designed to help users get real jobs done?
Two threads have been running through my mind recently, and I keep finding connections between them that I can't shake. The first is Diataxis - a structured framework for documentation that divides all docs into four distinct types: tutorials, how-to guides, reference, and explanation. The second is Clayton Christensen's jobs theory, which asks a deceptively simple question: what is the job that your customer needs to get done?
Side note: I've been heavily inspired by Clayton Christensen's books recently, and have audiobooked my way through Innovator's Dilemma/Solution/DNA, as well as Competing Against Luck. All good books, 100% recommended if you're interested in understanding how innovation actually works.
Here's the key insight: your documentation isn't competing with other documentation. It's competing with every other way someone could accomplish their job.
When someone opens your internal documentation, they're looking for more than information. They're trying to accomplish something specific, and they're evaluating whether your docs are the right tool for that job.
For internal company documentation—whether it's for internally built software, processes, or systems—the competition is different but equally real. Your how-to guide competes with asking a colleague, digging through Slack history, or reverse-engineering from existing code. Your reference docs compete with reading the source code directly, checking configuration files, or experimenting in a staging environment.
Diataxis Doc Type | Jobs to be Done (JTBD) | Alternative Product Categories That Could Be Hired |
---|---|---|
How-to Guides | "Show me how to achieve a specific outcome." | Asking a colleague, Slack/Teams search, reverse-engineering from existing code, trial and error in staging |
Reference | "Give me exact technical information I can look up quickly." | Reading source code, checking config files, database schemas, API endpoint testing, environment variables |
Explanation | "Help me understand how/why it works." | Architecture diagrams, code comments, git history, team knowledge sharing sessions, design documents |
Tutorials | "Help me learn by doing, in a safe structured way." | Pair programming, shadowing a colleague, sandbox environments, local development setup walkthroughs |
Once you see this competition, it reframes how you think about documentation structure.
Here's what's fascinating about internal documentation: the competition is actually pretty terrible. Think about it:
This means that even moderately good internal documentation has a much lower bar to clear than external documentation. Your internal how-to guide doesn't need to compete with polished YouTube tutorials - it just needs to be better than interrupting Sarah from accounting or spending 30 minutes searching through #engineering-general.
This is actually a huge opportunity. While external documentation faces fierce competition from Stack Overflow's crowdsourced answers and professionally produced tutorials, internal documentation often competes with... nothing systematic at all.
The result? Even basic improvements to internal documentation can have outsized impact on team productivity. When your reference docs are faster than reading source code, people will use them. When your how-to guides are clearer than tribal knowledge, they become the default choice.
Most documentation is written from the perspective of the product being documented. It's organized around features, capabilities, and technical architecture. But when you flip the perspective to focus on jobs-to-be-done, you can structure information more effectively around what readers actually need to accomplish.
Let me show you what this looks like in practice. Say you're writing a how-to guide for deploying your company's internal microservice. The traditional approach focuses on what information to include. The job-focused approach starts with the specific outcome: "Help me get this service deployed so I can test my feature and merge my PR."
That job-focused lens shifts how you structure the guide:
Every decision gets filtered through the lens of "does this help the reader accomplish their job better?"
The result? Documentation that people actually use because it's genuinely better at helping them accomplish their jobs.
Start by identifying the specific job your reader is trying to accomplish. Not the general topic area, but the specific outcome they need to achieve. Then ask yourself:
For that third question especially, consider using AI to help you think through different structural approaches. You can prompt an AI with the specific job your reader needs to accomplish and ask it to suggest multiple ways to organize the information, then choose the approach that best serves that job.
Take reference documentation as an example. The job goes beyond providing comprehensive information about all internal API endpoints or configuration options. The real job is "give me exact technical information I can look up quickly." This means your reference docs need to be faster and more precise than someone could get from reading your source code, checking configuration files, or asking in Slack.
If someone can figure out what they need faster by just reading the source code or asking a colleague, your reference docs aren't doing their job.
Here's where this gets really interesting. When documentation is designed around jobs-to-be-done, it creates a positive feedback loop that extends beyond the direct reader.
Well-structured, job-focused documentation helps humans and also helps AI systems understand context and provide better assistance to future users. When your how-to guide is crystal clear about the specific outcome it helps achieve, an AI can better understand when to recommend that guide to someone with a similar job.
The result is that good documentation becomes a force multiplier. Beyond helping the direct reader, it helps AI systems help other readers accomplish similar jobs faster and more accurately.
This creates a flywheel effect: better documentation helps more people accomplish their jobs, which generates more usage data and feedback, which leads to even better documentation that helps both humans and AI serve users more effectively.
The next time you write internal documentation, start with what job your reader is trying to accomplish rather than what you want to explain.
Ask yourself: if someone could accomplish this job faster or more reliably using a different approach, why would they choose your documentation instead? For internal docs, this question often has a surprising answer: because the alternatives are genuinely worse.
This is liberating. Your internal documentation doesn't need to be perfect - it just needs to be better than the current chaos of tribal knowledge and ad-hoc problem-solving.
When you can answer that question clearly, you'll write documentation that people find genuinely useful. And when people use your documentation successfully, they become more successful with your product.
This matters because documentation is ultimately about scaling our collective knowledge and decision-making capacity. But that scaling only happens when people actually use the documentation. And people only use documentation when it helps them accomplish specific jobs they need to get done.
For internal documentation, this scaling opportunity is especially significant. Every time someone uses your docs instead of interrupting a colleague, you're not just solving one person's problem - you're preserving focus and momentum across your entire team.
That's the value of thinking about internal documentation as a product designed around jobs-to-be-done. It creates a better experience for everyone who interacts with your work, and unlike external documentation, you don't need to beat world-class competition to succeed.
@article{
ericmjl-2025-the-job-your-docs-need-to-do,
author = {Eric J. Ma},
title = {The job your docs need to do},
year = {2025},
month = {07},
day = {07},
howpublished = {\url{https://ericmjl.github.io}},
journal = {Eric J. Ma's Blog},
url = {https://ericmjl.github.io/blog/2025/7/7/the-job-your-docs-need-to-do},
}
I send out a newsletter with tips and tools for data scientists. Come check it out at Substack.
If you would like to sponsor the coffee that goes into making my posts, please consider GitHub Sponsors!
Finally, I do free 30-minute GenAI strategy calls for teams that are looking to leverage GenAI for maximum impact. Consider booking a call on Calendly if you're interested!