Technical Writers’ Companion

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Printable Version
Save Permalink URL

Printed manual, online help, or both?

Printed manuals can be shipped on paper, or they can be shipped electronically as PDFs and then viewed on screen or printed on an office printer.

Printed manuals have a given order of pages. Even if readers don’t read the full document, you can at least expect them to view a number of pages in the given order.

Online help systems are essentially hypertext, regardless of the fact that most online help systems also have a hierarchical table of contents that suggests a particular hierarchy and sequence of topics.

Help topics are typically independent, linked pieces of information. They can be read in any order.

Expand /Collapse All Subsections

Advantages of printed manuals

▪Most people find reading long texts on paper more pleasant and less tiring than reading long texts on screen.

▪A large piece of information is visible. Skimming the text is easy.

▪It’s easy to make out the context into which specific information is embedded. Readers can readily see what comes before and what comes after.

▪The given order of topics can’t be changed, so there’s a preset route through the document.

▪Users can read a printed manual anytime and anywhere, for example, while commuting to work. They don’t need to have the actual product available.

Advantages of online help

▪Help can be context-sensitive, taking the reader directly to the relevant information.

▪It’s easy to follow links to other topics.

▪Help can be interactive (see Should you add interactive features?).

▪Help can be collaborative (see Should you add social features?).

▪Help can easily be updated.

▪There aren’t any printing and shipping costs.

▪Help can’t be lost or locked away in a colleague’s desk or cabinet.

Recommendations

In general:

▪For conceptual information, when possible use a printed manual as the primary medium.

▪For procedures and for reference information, when possible use online help as the primary medium.

▪Local laws and standards may require you to ship printed documentation along with your product. In particular, you must often provide safety instructions on paper.

If your product is hardware:

▪Always supply a printed manual.

▪If you don’t ship a printed manual but only an electronic manual (PDF) on a CD or as a download, be aware of the fact that you’re trading in some positive user experience for the money that you save.

▪As a compromise, consider providing at least a short printed manual that takes users through the first steps. In addition, you can provide information electronically for more advanced users. (Note: If you do so, in the printed document explain precisely where users can find the electronic documents. Provide the exact URL from which they can download or access the electronic documents. Don’t just refer them to your web site in general and let them search on their own. This provides a very negative user experience and deters many users from taking a look at these documents.)

▪For devices that are extremely simple to use, you may not need a printed user manual at all. This can both save costs and explicitly market your product’s ease of use.

▪Sometimes, all information can be included directly in a product (see Can you embed help?).

▪Sometimes, user instructions can be printed onto the packaging.

If your product is software, or if your product is controlled by software:

▪Always supply online help. Don’t force users who are working on their computers to switch the medium when they need assistance.

▪Provide genuine online help—not just a PDF, which is essentially paper on screen.

▪When possible, provide a PDF as an extra service for users who want to print out the information in the form of a manual. Use a single source publishing tool to generate both the online version and the printed version from a common text base.

▪Provide printed information for things that are important before users can even access online help. Typical examples are system requirements and installation instructions.

Single source publishing

Appropriate authoring tools enable you to generate both printed manuals and online help from the same, shared text base.

On the technical side, single source publishing can be achieved quite simply. The challenge is on the editorial side: You must structure and formulate all content in a way that guarantees that there won’t be any loss of quality in any of the generated versions.

▪Build modular content. Set up topics that can stand on their own and don’t need to be read in any particular order. Don’t assume that readers have read any other particular information before they get to a topic.

▪Don’t use any phrases that are specific to a particular medium, such as “manual,” “chapter,” “preface,” or “appendix,” which are specific for printed documents but out of place in online help.

▪Phrase cross-references (links) in a way that works for both mediums. Make sure that page numbers and phrases like “on page” don’t appear in online help.