Nobody reads the Docs (And that's our fault)

Ask any FOSS maintainer what frustrates them most about their users, and you will hear some version of the same answer: nobody reads the documentation. Users open an issue that the README answers. They ask in the community chat what the getting-started guide explains in detail. They watch a ten-minute YouTube video made by a stranger instead of reading the official docs that took months to write.

The easy conclusion is that users are lazy. The harder, more honest conclusion is that we built something they do not want to read.

This talk is a direct challenge to how the documentation community thinks about its own work. As a technical writer at Red Hat and an open source contributor, I have spent years writing documentation that followed every best practice, structured authoring, clear headings, consistent voice, proper versioning, and watched users route around it anyway. This talk is about what that taught me.

We will look at the structural reasons documentation gets skipped: the wall of text that greets a first-time user, the reference doc masquerading as a tutorial, the getting-started guide written by someone who no longer remembers what it felt like to not know the thing. We will look at what users actually do instead of reading the docs and what that behaviour is trying to tell us about the gap between the documentation we produce and the documentation people need.

This is not a talk about writing better sentences. It is a talk about whether we are building the right thing at all. It will challenge the assumption that good documentation is documentation that is complete, and argue instead that good documentation is documentation that gets used and that closing that gap requires technical writers and FOSS communities to be honest about some uncomfortable things: who we imagine our reader to be, what we optimise for when nobody is measuring impact, and why "the docs exist" has become an acceptable substitute for "the docs work."

The talk ends not with despair but with a reframe, a different way of thinking about documentation success that FOSS projects of any size can act on immediately.

1. The five structural reasons users skip documentation, and which ones are actually the writer's fault vs the format's fault

2. How to tell the difference between documentation that exists and documentation that works, and why FOSS projects routinely confuse the two

3. What user behaviour around docs is actually signalling about gaps in official documentation

4. A practical reframe of documentation success from "completeness" to "usage" and what that changes about how you prioritise your writing time

5. Three things any FOSS project can do immediately to close the gap between the docs that exist and the docs that get read