Deciding on the type of document

From TechWriter Wiki

Jump to: navigation, search

Contents

Introduction

Most documents produced by the Technical Communicator typically fall into the broad category of technical documentation. With this in mind, the majority of this page focuses on the principal types of technical document, and the purpose, content, and style of each of these.

Things to consider:

  • Decide what information goes in which type of publication;
  • Decide on the type of document(s) based on the type of information required by the readers;
  • Consider producing multiple documents for multiple audiences.

Technical documentation

Technical documentation may vary in scale from the full suite of documentation necessary for the maintenance and operation of a large industrial complex, to the instructions supplied with a domestic appliance, or the information supplied with a consumable commodity such as a tin of paint. They will vary in form from physical printed documentation to computer-based presentations designed to be viewed on screen.

BS4884, Specification for Technical Manuals, identifies the following categories of technical documentation:

  • Purpose and planning information;
  • Operating instructions;
  • Technical description;
  • Handling, installation, storage, transit;
  • Maintenance instructions;
  • Maintenance schedules;
  • Parts list;
  • Modification instructions;
  • Disposal information.

BS4884 goes on to state that "All required documentation for a product can be included under one of these categories. Between them, these categories comprise the total documentation set that could conceivably be required."

BS4884 was referring specifically to hardware, but many of these categories are also applicable to software. It is therefore worth examining them in a little more detail.

Note:
For an alternative classification, see Information Mapping's seven basic information types.

Purpose and Planning Information

This category contains information which allows potential users to assess the suitability of the product for their requirements. This may include:

  • Performance data;
  • Operational requirements;
  • Environmental limitations;
  • Handling and manning requirements.

Style: Targeted at managers or buyers.

Specific document types:

Operating instructions

This category contains detailed instructions which tell the users how to operate the product safely and efficiently. These instructions should cover all tasks, whether operational, maintenance, running-in, and so on.

For software, this category comprises the bulk of the delivered documentation, in the form of user guides. Note here, though, that it may be necessary to provide separate user guides per category of user (for example, administrator versus end-user, or even by user role - as is often the case with ERP systems).

Style: Should be task-based.

Specific document types:

Technical description

This category contains a description of the purpose of the product, and the operating principles governing its use. This may include:

  • Product configuration;
  • Technical data (dimensions, weights, tolerances, etc.);
  • Theory of operation;
  • Equipment list (including optional accessories, etc.).

The purpose of this type of documentation is to provide enough information about the product to allow the tasks described in the 'Handling, installation, storage, and transit', 'Operating instructions', and 'Maintenance instructions' to be carried out.

Style: Descriptive.

Specific document types:

Handling, installation, storage, and transit

This category contains information relating to the physical handling of the product outside of normal operation. This may include:

  • Installation instructions (including running-in or commissioning, etc.);
  • Preparations for different climatic and operational conditions;
  • Details of how to prepare the product for storage (from storing chemicals that may deteriorate, to 'mothballing' a warship or chemical plant);
  • Details of how to transport the product safely.

For software, this will likely only include the installation instructions.

Style: This information may be read only once.

Specific document types:

Maintenance instructions

This category contains details of the tasks that need to be carried out in order to ensure the continued operation of the product. This may include:

  • Routine maintenance;
  • Preventative maintenance;
  • Troubleshooting and repairs.

Style: Likely to be very detailed, but may be used only by trained experts. Troubleshooting section should be symptom-based.

Specific document types:

Maintenance schedules

This section should list the periods at which the various tasks identified under 'Maintenance instructions' should be carried out, and also identifies who should carry out these tasks (e.g. return to manufacturer, etc.).

Style: May be referred to by novice users, to decide when to call in the maintenance engineer. Should therefore be clear and generally non-technical.

Specific document types:

Parts list

The contents of this section should allow the users of the product to identify every part of the product, and to obtain spares if required.

Style: Is likely to consist of one or more illustrations and tables of parts/part numbers.

Specific document types:

Modification instructions

This section contains details of the authorized changes or upgrades that can be made to the product (such as the installation of a duplexing unit on a printer).

For software, this would include details of all possible 'user exits' and configuration settings.

Style: As for maintenance instructions

Specific document types:

Disposal information

This category includes details of how to dispose of the product safely (for example, disposal of hazardous waste, etc.).

For software, this would be the uninstallation instructions.

Style: Likely to be read only once. Probably descriptive, but likely to be very specific, for legal reasons.

Specific document types:

Documentation Sets

It is not always necessary, or even desirable, for all of the information for any given product or system to be contained in a single publication. Although it is sometimes tempting to produce a single 'User's Guide', it is quite likely that there are actually several categories of 'user', all of whom require different information about the product, and at different stages of the product's lifecycle.

You should therefore decide whether a single document is the most practical solution, or whether it makes sense to split the information to be provided into several distinct documents (or publications). Some possible criteria on which to base a decision of how to split the documentation include:

  • The audience of each category of information;
  • The frequency of use of each section;
  • The frequency of update of each section;
  • The product configuration (for example by part, area, or function);
  • The reproduction method required for specific information;

These criteria are discussed in further detail below.

The audience for each category of information

For any given product or system, there are likely to be a number of different categories of users, each of which may require different information about the product. For example, consider an enterprise-wide software system.

Installation and maintenance for this system is likely to be done by the Information Technology group, whereas the system will be used on a day-to-day basis by business users. Clearly, the business users do not need to know how to install the software, and the Information Technology group does not (necessarily) need to know how to use the system. In this case, it may be wise to provide two separate publications:

  • An Installation Guide, and
  • A User Guide.

'The frequency of use of each section With many publications, it is unlikely that the user will need to refer to all of the information all of the time. If the publication is particularly voluminous, then forcing the user to carry around (or even just remove from the bookshelf) a telephone directory sized publication when they only need to refer to half a dozen pages.

For example, with a complex system, users may initially need detailed instructions on how to use the product. Once they are familiar with the product, they will likely never refer to this information again. Instead, they are likely to refer to the documentation only when they have a problem, and at that point will want specific information.

Navigation considerations

With documentation sets, additional thought should be given to navigation aids across the set of documents as a whole. In particular, you should consider the following:

  • Tables of content
  • Indexes
  • Documentation summaries

Documentation summaries

Where multiple documents are being produced that together comprise the full set of information for a product, system or other 'thing' being documented, it is often useful to provide a summary of the full set of documents within each of the documents. This will allow users to confirm that they are reading the correct document, and/or see where to find the information that they are looking for, if it is not in the current document.

Example:

Available documentation

The following documentation is available for this software application.

Installation and Administration Guide
Provides instructions for installing and configuring the application in a multi-user environment, as well as information on how to add and manage content authors.
User Guide
Provides information on how to use the application to create content.
Messages and Codes
Lists all of the error messages and error codes that may be displayed during use of the system, and describes the steps required to resolve them.

In addition to these printed documents, additional help is available via the embedded on-line help.

Tables of Content

Consider providing a complete index to all of the documents at the start of each document.

Indexes

Consider providing a full index that covers all documents within each document.

Personal tools
Support