How should you name your documents?

Print topic Print topic Previous topic  Next topic

Name each document so that users can immediately see:

what information the document provides
(Which product is described? Which features and tasks are covered?)

what type of information the document provides
(Concepts? Procedures? Reference information?)

Expand /Collapse All Subsections

General rules

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 (see 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.

 

No:

DemoProduct Installation Manual
DemoProduct User’s Guide
DemoProduct Reference

Yes:

DemoProduct Installation Manual
DemoProduct User Manual
DemoProduct Reference Manual

or:

DemoProduct Installation Guide
DemoProduct User’s Guide
DemoProduct Reference Guide

Active titles vs. passive titles

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.

 

No:

Installing DemoProduct
DemoProduct User’s Guide

Yes:

Installing DemoProduct
Using DemoProduct

or:

DemoProduct Installation Guide
DemoProduct User’s Guide

Titles for online help

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

No:

Using DemoSoft

No:

Online help for DemoSoft

No:

DemoSoft Online Help

No:

DemoSoft 4.0 Help

Yes:

DemoSoft Help

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

Yes:

SampleSoft User Help
SampleSoft Administrator Help

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

Yes:

DemoSoft tutorial

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

Yes:

Getting started with DemoSoft

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.

Yes:

DemoSoft Parameter Reference

Yes:

DemoSoft API Reference

Typical publications for all users

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.

 

Yes:

DemoProduct User’s Guide
or:
Using DemoProduct

Yes:

DemoProduct Operator’s Manual

Yes:

DemoProduct Getting Started
or:
DemoProduct Getting Started Guide
or:
Getting Started with DemoProduct

Yes:

DemoProduct Assembly Instructions
or:
Assembling DemoProduct

Yes:

DemoProduct Installation Guide
or:
Installing DemoProduct

Yes:

DemoProduct Quick Reference

Yes:

DemoProduct Reference
or:
DemoProduct Reference Guide
or:
DemoProduct Reference Manual

Yes:

DemoProduct Safety Instructions

Typical publications for administrators

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

Administrator’s Reference
Encyclopedic information about particular product features.

 

Yes:

DemoProduct Administrator’s Guide
or:
Administrating DemoProduct

Yes:

DemoProduct Administrator’s Reference

Typical publications for developers and engineers

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.

 

Yes:

DemoProduct Developer’s Guide
DemoSoft Programmer’s Guide

Yes:

DemoProduct Technical Reference
DemoSoft Programmer’s Reference

Yes:

DemoProduct Maintenance Guide
or:
DemoProduct Service Manual

Yes:

DemoProduct Repair Manual


Layer information