Documentation Is Boring. Until Someone Can't Ship Without Them.

Nobody wants to write docs. Developers skip them, maintainers might defer them, and contributors treat them as an afterthought. Until a user files an issue that's just a missing example. Until a new contributor spends three days figuring out what the README assumed they already knew. Until your project's adoption stalls not because the code is bad, but because nobody could figure out how to use it.

I've triaged hundreds of documentation issues on OpenTelemetry and one of the largest multi-language open-source projects and the same failures show up over and over. Docs written for the person who built the feature, not the person trying to use it. Tutorials mixed with reference material. Getting-started guides that assume too much. Pages that technically answer the question but make you feel stupid for asking.

This talk is about fixing that. We'll cover the four doc types every project needs (and why mixing them up breaks everything), how to structure a page so developers can scan it and still find what they need, what "done" actually looks like for a doc before you ship it, and how to spot the difference between a doc that informs and one that just exists.

• The four doc types (tutorial, how-to, reference, explanation) and why conflating them is the most common docs mistake in open-source projects

• A practical structure checklist for writing a doc page that developers finish reading

• How to write for scanners without losing depth and the formatting decisions that actually matter

• A before/after framework for auditing existing docs in your own project