Technical Writers’ Companion

▪Make document titles as short as possible.

▪Include the product name in the title.

▪If you begin a title with a product name, add a line break after the product name if possible.

▪Create a title that clearly communicates the dominant information type within the document (concepts, procedures, reference).

▪When applicable, clearly state as part of the title for which audience (user group) the document has been designed.

▪When possible, choose a common document type so that users know what to expect (siehe lists of typical publications at the end of this topic).

▪If you supply only a single document along with your product, the need to communicate the document type, information type, and audience is less important. In this case, you can also choose a more engaging title. For example, you could call a manual Driving your FancyCar instead of FancyCar Owner’s Manual.

▪Include the product version number on the title page, but don’t make it part of the title.

▪Name all of your documents in a parallel manner.

You can choose an active title such as Installing DemoProduct or a passive title such as DemoProduct Installation Guide.

▪Use an active title

▪for consumer products

▪when you can be rather informal

▪Use a passive title if you need to be very formal.

▪Keep everything parallel. Use either active titles for all of your documents or passive titles for all of your documents.

For general online help, use a combination of the product name plus the word help. You can omit the word online.

Specify the kind of help only if there are different help systems available.

If you provide a separate tutorial, use a combination of the product name plus the word tutorial.

If you provide separate getting started help, use a combination of the words Getting started with plus the product name.

If you provide separate help files that contain specific reference information, use a combination of the product name and some specification what the reference is about, plus the word reference.

▪User’s Guide
Main printed manual. Often, it’s also the only printed manual.

▪Operator’s Manual
Manual that explains how to operate a machine, especially if this machine is used in an industrial environment.

▪Getting Started
Basic installation and setup information; often combined with a tutorial.

▪Assembly Instructions
Information on how to assemble a product.

▪Installation Guide
Information about how to install software or about how to mount a product.

▪Quick Reference
Concise information about commands, features, or components of a product.

▪Reference
Detailed information about commands, features, or components of a product.

▪Safety Instructions
Information about risks that may be involved in using a product plus instructions on how to minimize the risks.

▪Administrator’s Guide
Information about installing, configuring, and managing a product.

▪Administrator’s Reference
Encyclopedic information about particular product features.

▪Developer’s Guide (used in general), Programmer’s Guide (used with software)
Explanation of development concepts and techniques.

▪Technical Reference (used in general), Programmer’s Reference (used with software)
Technical information required to integrate and adapt the product.

▪Maintenance Guide, Service Manual
Procedures and technical information needed to service a device. Often, this also contains some repair information if there isn’t a separate repair manual.

▪Repair Manual
Manual that exclusively contains repair information.