The Case for Web Manuals

It is much harder to reduce complexity than to create something simple from scratch. But someone has to do it.

There is “the right way” to do something.

And if done right, the result will be beautiful, well-defined, and a joy to look at.

You just have to find it in the sea of all possible configurations.

1. The case for web manuals

If you build and sell well-designed, beautiful, high-end products, your customers will want documentation that reflects your brand’s aesthetic and philosophy. They may not ask for it right away – but they will notice the dissonance between a high-quality product and poorly made, hard-to-read documentation.

Let’s see how such a frustrating user experience can be avoided.

1.1 What’s wrong with PDF manuals?

An outdated metaphor / model

Many consumer and professional AV technology brands still make their product manuals available as downloadable PDFs. Let us outline why this is a problematic approach.

PDFs are essentially “digital paper”.

PDF is a _page-based format that was developed more than 30 years ago – for a world still dominated by, well, paper, fax machines, and snail mail.

This is not the world most people live in today.

A PDF always has…

• a fixed, physical size (A4, A5, US Letter…),
• ratio
• and orientation (portrait, landscape, square).

The real world in 2025, on the other hand, is dominated by lightweight smartphones, tablets, notebooks, and – on the other end of the spectrum – high-end, high-resolution 4K / 5K screens.

This leads to an astounding spectrum of display sizes and resolutions. Consider the ≥50 factor between a smartwatch display’s 0.165 MP and a (3840 × 2160 pixel) 8.2 MP Ultra-HD screen.

No fixed-size document – no matter how beautiful and well-designed it may be – scales that much, so your users will have to zoom, pinch, and move around a lot to read on whatever mobile device they are using. And they won’t enjoy it.

Breaking the user experience

These days, it’s likely that most of your customers and partners primarily read and process information published on the web, aka HTML documents. Accordingly, the web browser is the reading and working environment they will be most comfortable with – possibly fine-tuned using extensions, and well-learned shortcuts.

Forcing a user to download a documentation in a binary format and open it in a separate application or browser module can cause frustration, especially for technically challenged users.

The PDF viewer on a generic smartphone may have totally different features, controls and display / rendering quality than the browser – usually worse.

1.2 What’s wrong with legacy document formats and typesetting software?

Updating documentation – for example, after product firmware updates – often requires digging up sources in legacy formats, leading to delays, extra work, and cost.

Many well-known and beloved brands have been around for decades. The same is true for their product manuals.

And as no one enjoys spending money on anything legacy, many older manuals now are “islands”: folders sitting on a graphic designer’s hard disk, with Microsoft Word or InDesign files and illustrations in dozens of variations that may or may not be editable by your company’s writers and designers in 2025.

The results are collections of PDFs that look severely outdated or inconsistent. This is not a look you want your brand to be associated with.

1.3 Data silos make life difficult for everyone

The story doesn’t end with static PDF product manuals. In most companies, product information is spread over separate “data silos” – closed file formats, storage systems, or platforms. This makes creating, updating, and translating content unnecessarily hard. It also forces dealers and end users to jump between these systems when they are looking for specific information.

An open, format-agnostic approach to documentation has immediate benefits:

• All content contributors can use the same toolset for creating and updating content.
• Translation becomes more efficient, as only one workflow and one translation management system have to be set up.
• Both end users and search engines will find all relevant information in one place.

2. HTML to the rescue

2.1 HTML has eaten the (publishing) world

The foundations of the web – HTML, CSS, and JavaScript – are a well-proven toolset for, well, pretty much everything: news, marketing sites, social media, scientific papers… and product documentation.

2.2 Web manuals, FAQs, quick guides, etc., are already everywhere

Examples:

• Apple iPhone User Guide
• Adobe Photoshop User Guide
• Mercedes EQE Owner’s Manual
• Teenage Engineering OP-1 Manual

2.3 HTML + CSS = stable and scalable

With carefully prepared templates and responsive style sheets, web manuals will look fine on devices of all kinds and sizes – legacy, current, and future.

2.4 Web manuals are first-class web citizens

Web manuals are HTML plus CSS and (optionally) JavaScript. When publishing product documentation as web manuals, you immediately benefit from the most popular technology stack in the world, and from all the money and know-how that has been invested in browsers, rendering engines, and indexing technology.

2.5 Great for SEO

Web manuals are web pages, making them easy to read and process for search engines, which means that investing in web manuals will increase visibility of relevant product information.

2.6 Great for your clients and business partners

Content that is easy to find and easy to read will not only benefit end users, but also other stakeholders as well:

• distributors (who will benefit from machine-translatable content even if they don’t want to pay for documentation localization
• dealers (who will find it easier to look up technical information both for new and legacy products)
• support specialists (who can send users directly to the relevant information instead of telling them “It’s somewhere in the manual”)
• all the other institutions and people you’re working with (such as journalists, external developers, standards organizations…) who have enough work and problems on their plates already.

Make everyone’s lives easier while saving money in the long run. This should be an easy decision to make.

2.7 Great for users with vision impairments / older users

Web manuals are HTML documents. This means they can be easily processed by special screen reader devices or applications and the “read mode” of modern browsers. This is great for users who have difficulty reading small text.

2.8 Translation – for free

It’s an open secret that by now, machine translation quality is rivaling professional human translators for many language pairs, document types, and industries.

• Modern browsers now have built-in machine translation capabilities. This means that even for (legacy) manuals where you don’t want to spend money on translation, you can rely on Chrome, Safari & Co. to provide translations of your web manuals to the most relevant target languages in acceptable or even excellent quality.

• It is also possible to create server-side links that will forward users to machine-translated versions of a page at translate.google.com.

2.9 Future-proof

HTML will never go away – well, at least not for the next 20 or 30 years. And even if there should be newer HTML versions down the road, billions of web pages ensure that browsers will be backwards-compatible for decades.

Granularity

You may not have heard that term before, but granularity is a Really Big Deal™.

Granularity ensures that in a given complex document (set), small, relevant fragments (that one sentence with that one information your users have desperately been looking for) can easily be identified and referred to using a standard web mechanism called fragment URLs.

Put simply: If a question is being asked over and over again, your support employees can send users not just to “the site” or “the manual”, but to a specific sentence in a specific paragraph in a specific chapter of a specific manual. Now that’s precision.

3. Semantic documentation

It is possible (with some extra work both for authors and coders) to add machine-readable payload – in JSON-LD format – to HTML web manuals. Google, Bing, and other search engines / indexers can process that information and expose it to end users directly, making everyone’s lives easier.

And now new search engines such as Perplexity that use artificial intelligence to provide answers right on the results page are entering the fray. These engines take advantage of semantic HTML sources, allowing them to extract relevant information and save users time.

This allows for semantic web magic:

Users (and machines) can ask questions such as “What are the dimensions of that device?” and get not only a link to a page, but hard data – right on the search engine results page. It doesn’t get easier than this.

4. “But our brand still needs PDFs!”

And you shall have them. 😊

Well-formatted PDFs can be created from HTML documents using the power of Print CSS.

This is a “free” / built-in feature with modern browsers. The user just has to hit Print / “Save as PDF”.

For better quality and technically challenged users, HTML manuals can also be converted on the server to create “traditional” downloadable PDFs.

There are two options here:

1. “Headless” conversion using a generic web browser’s PDF engine.
2. Commercial HTML / XML to PDF converters: This will yield better results, especially for complex documents, but requires more elaborate configuration work, tests, and license fees for the conversion engine.

5. Core principles

5.1 Keeping things simple

While Specs and Docs is a relatively new offering, we have developed our workflow and core technology over a long time, essentially stripping away a lot of complexity to ensure the resulting system will be usable for a long time to come.

This is how we avoid all unnecessary complexity:

6. The beauty of Markdown

Markdown is one of the world’s most popular “file formats” / markup languages. For more information, see e.g. en.wikipedia.org/wiki/Markdown. It is an excellent base format for product literature such as manuals, quick guides, FAQs, and whatever else your brand may require.

6.1 Simple text-only markup

Using Markdown, authors can use hyphens, hash signs, and a few other characters to generate / place…

• structure (headings, lists),
• emphasis (bold, strong),
• illustrations,
• tables,
• links,
• footnotes, etc.

6.2 Easy to read and write

Markdown is easy to read for humans and easy to process for machines.

Markdown core concepts can be learned and applied even by non-technical users in about ten minutes.

6.3 No “coding”, no tools, no licenses required

Any text editor on any operating system will do. There are also many online tools for creating and converting Markdown files.

Markdown is also being used in GitHub and many content management systems.

Many extensions of the Markdown “core” syntax / concept exist for more advanced applications:

• document sections,
• node IDs,
• Math,
• citations
• etc.

7. “Fine. But why not do it all in our CMS?”

7.1 A CMS is not a great writing environment for long-form text

A typical “off-the-shelf” content management system isn’t a great environment for writing and structuring technical content. With our Markdown-based approach, your tech writers, developers, product managers, and all other stakeholders can easily create, modify, and comment on product literature without having to use specialized software or access your content publishing platforms. Documents can be shared and edited without conversion or access issues, even using messaging apps or any of the countless web-based collaboration tools.

7.2 Security considerations

As long as you’re working with external writers, proofreaders, and translation service providers, you do not want your third-party writer, designer, and ten translators waltzing around the CMS backend, with access to things they probably shouldn’t see / mess with.

So, unless you want to add a “gatekeeper” to the workflow, it’s probably best to keep both worlds (web publishing and documentation) separate.

7.3 Language “mapping”

The languages used and supported on your website and other marketing platforms may not align with the languages of your product documentation.

Here is an example.

Your brand operates websites in four languages / regions, all in the respective top-level domain, and properly interlinked:

• yourbrand.com (English)
• yourbrand.de (German)
• yourbrand.fr (French)
• yourbrand.dk (Danish)

However, you may want or need to make your manuals and other documentation available in English, German, French, Spanish, Portuguese and Korean (but not in Danish, as you know your Danish users will be perfectly happy with English documentation).

So – how do you make your documentation available to the respective audiences? The content management system’s language selectors will only go so far before you get to a messy, hard-to-maintain spiderweb of languages. This is why it’s probably a good idea to keep the language sets for the marketing domain (website, social media channels, etc.) and for product literature separate.

7.4 PDF creation and printing

Most content management systems (which are optimized for building and publishing highly modular web pages) do not support the creation of beautiful, long-form PDFs “out of the box”. It may be possible to print a page, and it may be possible to make it look good – but this will always require extra work by your designers and / or web agency.

Using our workflow, your business partners and end users can rely on manuals that look great on screen and can be converted to no-nonsense, well-formatted PDFs. And users can print just the information they need without wasting a ton of ink on elements they don’t need.

8. Deliverables

If you task us with converting, structuring, and “rendering” your documentation content for the web, this is what you’ll get from us:

8.1 Conversion of your existing documentation to Markdown format

Please note that while most “downstream” steps are automated, this is hard, manual, time-consuming work – and we’ll have to see your document sources to quote it properly.

8.2 Access to a conversion server

…with all installed / required software components.

8.3 Markdown source files

…for all your manuals, quick guides, FAQs, etc., as made available to us.

8.4 YAML configuration files

…containing metadata and variables that will ensure your manuals will be valid and properly linked to each other.

8.5 Manuals CSS

…ensuring your manuals meet your corporate design requirements.

8.6 Refined manual templates

Specs and Docs templates hold the “logic” / code that will use convert variables (such as “consumer product: true“ or “Europe only: true”) to create well-formatted information containing only the relevant information for a target group or locale.

8.7 Rendered HTML manuals

Web manuals are, in essence, valid static HTML5 files, with just some semantic CSS classes and a few lines of (optional) JavaScript applied. These HTML-based manuals can easily be hosted either by us or on-premises – it’s your choice.

8.8 Rendered PDF manuals

Our manuals come with a default print style sheet that strips away all unnecessary elements and formatting, leaving a clean, no-nonsense layout. Your end users and business partners can print these manuals directly from their browser without wasting ink or toner, with enough whitespace for their notes. Print style sheets can also be customized – e.g., if your brand or industry prefers a more compact, paper-saving layout.

In addition, we are offering server-side or offline PDF rendering options.

↻ 2025-08-21