What If the Best Documentation Isn't Text?

Documentation has a default format, and that format is text. Paragraphs, headings, bullet points, code blocks. We have built entire toolchains around it, static site generators, markup languages, style guides, and linters. We have professional communities dedicated to writing it better. And for a large category of documentation needs, text is exactly the right answer.

But this talk asks an uncomfortable question: what if we have been reaching for text out of habit rather than judgment?

Consider what users actually do when they get stuck. They search YouTube. They clone a repository and read the code. They find an interactive playground and start pressing buttons. They ask a question in a community chat and get unstuck in three messages. They open a tool, hit an error, and read a message that either tells them exactly what went wrong and how to fix it or sends them spiralling through three documentation pages that almost answer the question. In each of these cases, the most useful "documentation" was not a page of prose.

As a technical writer at Red Hat and an open source contributor, I have spent years making text-based documentation as good as it can be. This talk is my honest reckoning with the cases where that was the wrong investment.

We will look at the formats that often serve users better than text for specific documentation jobs: interactive playgrounds that let users learn by doing rather than reading, annotated code examples that put explanation at the point of need, well-crafted error messages that document failure states in context, diagrams that communicate system architecture in ten seconds that a page of prose cannot communicate in ten minutes, and video walkthroughs for tasks where sequence and visual feedback matter. We will look at real FOSS projects that have made deliberate choices about format, not defaulting to text, not abandoning it, but actually asking which format serves the reader for this specific job.

This is not a talk against writing. It is a talk for intentionality for documentation communities that choose their format based on what the reader needs to accomplish, rather than what is easiest to produce and version control. It will challenge technical writers to think of themselves not as people who write documentation but as people who solve the problem of users getting stuck, and to pick up whatever tool actually solves that problem.

1. A practical framework for choosing documentation format based on the user's actual job-to-be-done when text wins, when it loses, and how to tell the difference

2. The specific documentation jobs where interactive examples, annotated code, error messages, diagrams, and video consistently outperform prose with real FOSS examples

3. How to make the case inside a FOSS project or organisation for investing in non-text documentation formats the arguments that actually land with maintainers and engineering teams

4. A reframe of the technical writer's role from "person who writes docs" to "person who solves the problem of users getting stuck" and what that shift unlocks

5. A checklist for auditing your existing documentation to identify where a format mismatch is silently causing user drop-off