A user downloaded the 340-page PDF manual for a software product. They were looking for the configuration parameter that controlled the connection timeout. The PDF had a table of contents, which linked to chapters but not to sections. They opened the document search, typed “timeout,” and got 47 results across the document. They scrolled through them. The right answer was on page 211. There was no way to bookmark it in the browser. There was no way to link a colleague directly to that section. They took a screenshot and pasted it into Slack.
This is PDF documentation working as designed. It still took the user twenty minutes to find one fact.
PDFs are static. They were designed for a world where distributing a document meant printing it or emailing a file. That world still exists, but it no longer includes software documentation that changes with every release, answers questions users didn’t anticipate, and needs to be found through search before it can be read.
The structural problems with PDF for software documentation are practical. You can’t search across multiple PDF files the way you can search a documentation site. You can’t link directly to a specific section without complex anchor syntax that most PDF viewers don’t reliably support. You can’t update the document without republishing and redistributing it, which means users who downloaded the old version have no way of knowing something changed. And PDFs age silently: a document from three years ago sitting on a download page looks exactly as authoritative as one published last week.
The reading model that PDF enforces — linear, paginated, sequential — is exactly what Mark Baker described at everypageispageone.com as the model the web has made obsolete. Readers don’t follow the page sequence. They search, skim, and jump. PDF makes this difficult by design.
There are real use cases for PDF in documentation. Regulatory compliance documents often need to be archived in a fixed format. Print manuals for physical products — equipment, hardware, devices that users might operate away from a screen — make sense as PDFs. Contracts, certificates, formal documentation that needs to be signed or submitted: PDF is right for all of these.
Software documentation that changes more than once a year is not on that list. Configuration guides, API references, integration tutorials, onboarding flows: these need to be searchable, linkable, updatable, and discoverable through search engines. HTML does all of these. PDF does none of them well.
The argument for PDF is usually about appearance: it looks professional, it’s a branded deliverable, it feels complete. These are not bad things. But “looks professional” is a poor trade for “users can’t find what they need.” The goal of documentation is to help users succeed. Format decisions should serve that goal.
If you’re producing PDF documentation for software because the format feels authoritative, consider who it serves: you, or the user looking for the timeout parameter on page 211.