What Job Does Your Documentation Really Need to Do?

Alternatively titled: Why your docs are competing with Slack, colleagues, and chaos (and why that's good news)

Hello fellow datanistas!

Have you ever wondered why people skip your internal docs and just ping you on Slack instead? Lately, I’ve been connecting two threads that keep popping up in my work: the Diataxis documentation framework and Clayton Christensen’s jobs-to-be-done theory. The more I think about it, the more I realize our docs aren’t just competing with other docs—they’re up against every possible way someone could get their job done.

This post is about reframing how we think about internal documentation. Instead of focusing on what we want to explain, I’m exploring what our readers actually need to accomplish—and how our docs can become the best tool for that job. I’ll share how this shift in perspective can make our documentation more useful, more used, and (surprisingly) easier to improve.

Here’s the key insight that’s been rattling around in my head: your documentation isn’t just in a race with other documentation. It’s competing with asking a colleague, digging through Slack, reverse-engineering code, or just plain trial and error. For internal docs, the competition is often pretty terrible—interrupting someone, searching endless chat logs, or poking around in staging environments. That’s actually a huge opportunity.

Even moderately good internal docs can have an outsized impact because the alternatives are so inefficient. If your how-to guide is clearer than tribal knowledge, it becomes the default. If your reference docs are faster than reading source code, people will use them.

The trick is to start with the job your reader needs to get done. Not just the topic, but the specific outcome they’re after. For example, instead of writing a generic deployment guide, focus on helping someone get their service deployed so they can merge their PR and move on. Every decision -- what to include, how to structure it -- gets filtered through the lens of, “Does this help the reader accomplish their job better?”

This job-focused approach doesn’t just help humans. Well-structured, outcome-oriented docs also help AI systems recommend the right resources to future users. It creates a flywheel: better docs help more people, which leads to more feedback, which leads to even better docs.

If you’re curious about how to apply this practically, I break down the types of docs (tutorials, how-to guides, reference, explanation) and the real-world alternatives they’re competing with in my full post. I also share how AI can help you brainstorm better structures for your docs, and why you don’t need to be perfect—just better than the current chaos.

Internal documentation doesn’t need to be perfect, it just needs to help people accomplish their jobs better than the messy alternatives. When you focus on the job to be done, your docs become genuinely useful (and used).

What’s the most surprising alternative you’ve seen people use instead of your documentation? How do you think your docs could do that job better?

If this resonates, check out the full post for practical frameworks and examples: The job your docs need to do. If you find it helpful, I’d love for you to share it or subscribe for more.*

Cheers,

Eric