Why HTML beats PDF for hardware tech docs
I recently attended the Information Energy 2026 virtual conference, which focuses on content strategy and technical communication. Like most tech writing events right now, AI was a dominant theme - how to write for it, how to use it, how to prepare your content for it. All useful and valuable stuff.
But one talk stood out to me for a different reason, and it wasn’t really about AI at all. It was about a problem I’m dealing with right now at work.
The problem: PDF installation guides
My current challenge is converting a set of PDF hardware installation guides into web pages. If you’ve done something like this before, you’ll know it’s not just about formatting. You have to think about structure, navigation, how to break up long linear content into something that actually works on the web. Image and diagram handling is a big part of it too. It’s made me think a lot about why PDFs are a poor fit for modern documentation delivery in the first place.
It’s worth being clear that I’m specifically talking about hardware documentation here. In the software world, the rise of docs-as-code has driven a real shift in how documentation is authored, managed, and published. Practices like version control, pull request reviews, structured Markdown, and continuous deployment have become increasingly common - even something of a standard. Hardware documentation hasn’t really followed the same path. Much of it is still authored in tools designed for print, delivered as PDFs, and tied to product release cycles in ways that make iteration difficult. Regulatory requirements are part of the reason - manufacturers usually have to provide formal, verifiable documentation and PDF has historically been the accepted format for that. But regulation is increasingly less of a blocker than it might seem, and I’ll come back to that later in this post.
The talk: Interactivity and HTML
Edgar’s Hellfritsch’s talk, Interactivity and HTML – Reasons to (Finally) Abandon PDF as Your Delivery Format of Choice, was a well-argued case for moving from PDF to HTML as the primary delivery format for technical documentation.
He opened with a relatable example: his electric car has a sophisticated app that lets him remotely control the windows, climate system, and more. It feels modern and connected. But when he tries to look up how to do something in the documentation via the same app, it dumps a 900-page PDF onto his smartphone. A jarring step backwards.
The talk identified a few core problems with PDF as a delivery format:
- It’s linear: Users have two navigation options - table of contents and full-text search.
- It’s monolithic: A 900-page manual might contain 300 pages that don’t apply to your specific product variant. And if you have a product line with many regional or model variants, you end up maintaining a large number of separate PDF documents - one per configuration - each of which needs to be updated independently whenever something changes.
- It’s passive: PDF is designed for reading, not interacting.
- It loses structure: The modularity and metadata you’ve carefully built in your CCMS, docs-as-code system, or whatever content management system you’re using is largely discarded in the PDF output.
Concrete examples that resonated
Edgar showed several practical examples of what HTML enables that PDF simply can’t:
- A safety warning with an “understand and confirm” button that forces users to acknowledge it before proceeding - a small interaction that meaningfully improves safety.
- A maintenance instruction linked to a machine’s HMI (Human-Machine Interface), displayed automatically when the machine reaches its service interval. The machine knows its own operating hours; the documentation just needs to be in a format it can use.
- An MRI (Magnetic Resonance Imaging) system manual with language switching independent of the UI language - important when misunderstanding an instruction could harm someone. And for maintenance it’s a huge win. Not producing multiple language variants of the same PDF, but just one HTML manual with structured metadata that allows users to select their language on the fly.
- A hazardous substances table transformed from five unusable pages on a smartphone into a searchable, filterable dataset with inline hazard code descriptions.
These examples made the case clearly. It’s not that HTML is technically superior in some abstract sense - it’s that HTML enables documentation to actually do things.
Another good real-world example of hardware documentation done well can be found on Flipper’s docs site. At a recent Write the Docs London meetup, Alexey Zakharov gave a talk about how Flipper approaches user documentation - structured, web-native, full of beautiful illustrations and genuinely useful. Their docs are a strong example of what’s possible when a hardware company treats documentation as a product rather than a compliance exercise.
The groundwork is probably already there
One point Edgar made that I found particularly encouraging is that most technical writing teams already have the building blocks for this kind of delivery. If you’re using a CCMS, or even in a docs-as-code system, you already have modular, structured, metadata-rich content. The problem is perhaps that many teams are using that structure to generate better PDFs rather than to deliver interactive HTML.
Worth noting: when I talk about “delivering HTML”, I don’t mean writing raw HTML by hand (or even getting an AI to do it for you). In practice, I author in Markdown, and a static site generator handles the HTML output. The structure and metadata live in the source - Markdown front matter, headings, shortcodes - and what you choose to render that source into is what changes. Switching from PDF to web is largely a build and architecture decision, not a rewrite.
He also made a point that connects back to the AI theme running through the rest of the conference: structured HTML content is much more useful to AI systems than PDFs. If you’re thinking about making your documentation AI-ready, moving to HTML (or indeed any structured, machine-readable format like Markdown) is a step in that direction. (Look ma’, an AI reference after all!)
What this means for my PDF conversion project
The talk reinforced something I’d been feeling already: the goal of converting our PDF installation guides shouldn’t just be to replicate the PDF content in a different format. It’s an opportunity to rethink the structure entirely.
A few specific capabilities HTML enables that I’m now thinking about more carefully:
Consolidating variants. With HTML, a product family that currently requires many separate PDF downloads - one per model, region, or configuration - can become a single guide with structured metadata and an interactive model selector. Update the content once and it applies across all variants.
Faceted search. Rather than plain full-text search, HTML guides can support filtering by structured attributes drawn from that metadata - product family, region, configuration, door thickness (I work for a company that makes smart locks), and so on. Installers find the right guide without needing to know its exact name or document number.
Semantic data values. In a PDF, a measurement is just a string. In HTML, it can be typed and machine-readable - which benefits screen readers, browser tools that convert units, and future integrations with product databases.
Guides as part of a wider network. The biggest conceptual shift is moving from a self-contained document to a node in a broader information network. An HTML guide can link out to relevant spare parts, certificates, firmware downloads, troubleshooting articles, and video walkthroughs - ideally from within the relevant installation step. That kind of connection is not available in a PDF, or at least very difficult to achieve.
There’s also a regulatory dimension worth noting. The EU Machinery Regulation (EU 2023/1230), which applies from January 2027, explicitly permits - and in many ways favours - digital delivery of instructions for use. For anyone working in hardware or industrial documentation, the shift to HTML isn’t just a user experience improvement; it’s increasingly a compliance consideration.
And the AI connection: what I really understood - both from Edgar’s talk and from working through this project - is that making documentation AI-ready and migrating it to well-structured HTML are essentially the same work. The structured metadata, typed data values, stable URLs, and consistent tagging that make guides useful for humans are exactly what makes them indexable and useful to AI systems. The AI benefit is a consequence of doing the migration properly, not a separate project on top of it.
In summary
Edgar’s talk was a practical and well-illustrated argument for why HTML should replace PDF as the default for technical documentation delivery. But the more I’ve thought about it in the context of my own work, the more I think the real value isn’t in the migration itself - it’s in what you can build once the content is properly structured and web-native.
Tech writers as strategic enablers anyone?