The documentation set plan describes the overall characteristics of a proposed documentation set. You might think of a documentation set plan as a publications architecture document, similar to an engineering specification.

For large documentation sets, the publications manager or project lead often designs the documentation set plan with input from individual contributors. For smaller sets, individual contributors might provide documentation set plans.

A document plan describes the characteristics of a specific manual. The document plan might include a content outline, production considerations, and an explanation about how an individual document will be implemented. Typically, the writer or project lead creates the document plan.

Manuals with a single chapter are usually small and narrowly focused on a single subject. Examples of manuals with a single chapter include the following:

The following table lists the components of a typical single-chapter manual. The components are listed in the order in which they usually appear within the manual. The optional components depend on the individual book. For example, you probably do not need a table of contents if the document has only one or two pages. Likewise, an index is unnecessary for a document of fewer than 20 pages. Manuals with a single chapter usually require title pages and legal notice pages.

Manuals with multiple chapters are the most common types of technical manuals. These manuals usually require a title page as well as front and back matter.

In addition to being divided into chapters, some manuals are further divided into parts. A part contains one or more chapters. Manuals can be divided into parts for various reasons. One example is a single manual that is both a user’s guide and a reference manual.

If a manual is divided into parts, the manual must have at least two parts. The parts must also be identified by a part divider page. See “Part Dividers” on page 177.

The following table lists the components of typical manuals with multiple chapters. The components are listed in the order in which they appear within a manual. Optional means that the component of the manual might be required in certain writing situations.

Most manuals have a title page, which contains the manual title, current address block, and release date. Your company’s specific information might also include elements such as the corporate telephone number and document revision information.

The legal notice contains various copyright and trademark statements.

The table of contents can list the first-level headings, second-level headings, and third-level headings in a manual. Headings can be numbered or unnumbered, depending on the style determined for your document.

A manual should have a table of contents if the manual has more than one chapter. The table of contents usually begins on a right page in a printed manual.

The list of figures lists all numbered figures in the manual. Consider including the list of figures if the manual has more than one numbered figure and more than one chapter. The list of figures usually begins on a right page in a printed manual.

The list of tables lists all numbered tables in the manual. Consider including the list of tables if the manual has more than one numbered table and more than one chapter. The list of tables usually begins on a right page in a printed manual.

The list of examples lists all numbered code examples and other types of examples in the manual. Consider including the list of examples if the manual has more than one numbered example and more than one chapter. The list of examples usually begins on a right page in a printed manual.

The preface describes the purpose and scope of the manual and includes an overview of the parts of the manual. The preface usually begins on a right page in a printed manual.

Depending on the purpose and complexity of the manual, the preface might contain all or some of the sections listed here. The preface might also contain sections specific to a documentation set.

First, explain the purpose of the manual in one or two sentences. Identify the level of technical sophistication that the reader must possess to use the manual effectively. Next, include sections similar to the following if the additional information is relevant to the book:

The three general types of chapter page numbering and heading styles are:

The type of page numbering style that you use is optional and depends on various factors such as personal preference, history of the manual, or the manual’s subject matter. All chapters begin on a right page in a printed manual.

Part dividers are used only in manuals that need to be divided into parts. See “Manuals With Multiple Chapters” on page 173. Part dividers are numbered with Roman numerals, for example, Part I, Part II, Part III, and so on, and include a title. The part dividers can have a cross-reference listing of the chapters that are included in the part. You might also include text and illustrations, either on the front or on both the front and back of the part dividers.

Part dividers begin on a right page in a printed manual. Part dividers do not have a page number in a printed manual. For more information, see “Part Dividers” on page 56.

Appendixes provide supplementary information to the main body of the manual. Appendixes appear at the end of the manual. Appropriate material for appendixes includes the following:

Do not use an appendix as a repository for “odds and ends” that do not benefit the reader’s grasp of the subject.

Appendixes can use numbered or unnumbered section headings, depending on the chapter style of the manual. For example, you would use numbered section headings in appendixes for manuals that use numbered section headings in chapters.

Each appendix is designated by a letter, for example, Appendix A, Appendix B, and so on. Each appendix begins on a right page in a printed manual.

A glossary is an alphabetical list of defined terms, phrases, abbreviations, and acronyms. The glossary defines terms that might not be clear to the reader.

The glossary is included within a manual in the following location:

The glossary begins on a right page in a printed manual.

Your publications department might have developed a glossary with more specific definitions for terms that are specific to your product area. For more information about glossaries, see Chapter 13.

A bibliography is a list of the sources to which you refer in your manual. Bibliographies follow a specific format for each kind of resource that is cited. A bibliography begins on a right page in a printed manual. For more information, see “Writing Bibliographies” on page 51.

An index is recommended for a manual of more than 20 pages. Indexes begin on a right page in a printed manual. For more information about indexing and index formats, see Chapter 14.

In general, there are two types of installation guides:

System overview guides are designed for users who are responsible for setting up and administering large server systems. These guides cover technical features and functions of the system.

User’s guides are written for users who are responsible for setting up and administering systems. User’s guides usually contain instructions for installation, configuration, and setup, as well as information about administration and troubleshooting.

Service manuals are typically prepared for platforms and storage systems rather than for a single board or a single device.

Many large companies have internal service organizations that use the service manuals to maintain their equipment. Therefore, the readers of service manuals might be experienced service technicians who work on a given company’s equipment only occasionally. When writing a service manual, you cannot make any assumptions about the reader’s knowledge of your company’s computers.

Configuration guides are typically written for families of products. These manuals tell the user how to fit the pieces together and how to add certain devices to the system configuration. This type of manual might also be used by Marketing to assist customers in meeting their installation requirements.

Software installation guides explain how to install and configure the software on the user’s system. When writing the manual, you must assume that the reader has already assembled the hardware and is awaiting instructions for installing the software.

Software programmer’s guides vary in scope, depending on whether you are discussing the programming features of the operating environment, a language compiler application, or an application programming interface (API). Typical operating system programmer’s guides might range from an application packaging developer’s guide, which is written for a general audience of applications developers, to a book about writing device drivers, which is directed to highly specialized system programmers.

Programmer’s guides explain how to write programs that take advantage of the features of the particular product. Compilers and language-development tools have their own documentation sets that are specifically geared toward programmers who use the tools.

System administration guides tell readers how to set up, maintain, and troubleshoot software activities on their computers, and, by extension, networks of their computers. The reader might be anyone from a novice to an experienced network manager.

User’s guides tell readers how to use the features of a software product. The guide’s complexity depends on how sophisticated readers must be to use the product. You might write the user’s guide for your product as a tutorial.

Reference guides give very specific details about a software product, such as syntax statements for programming languages or explanations of each feature of a graphics software package. Usually, the subjects are arranged in alphabetical order.

White papers are optional documents that are usually used to publicize a new product or a new feature before official documentation is available. Your involvement ensures that all product information is consistent with the product documentation, uses the standard documentation format, and meets company editorial guidelines.

When working on a white paper, you might interact with Product Marketing, Engineering, or other consulting groups regarding schedules, customer requirements, and other issues.

Online help is information that a computer displays to assist users in doing tasks. You might be required to write help text in addition to conventional manuals. Most products require you to use compatible help viewers and authoring tools.

Many software products are supplied on CD-ROM media. The textual pieces of the CD-ROM package are often considered part of the documentation set. These pieces are the following:

Release notes for software products and product notes for hardware products are the final documents that are written before a product ships. The purpose of these notes is to inform the customer about any major problems with hardware, software, or documentation that were discovered after the manuals were printed. Release notes also contain other late-breaking information and additional information needed at installation.

Release notes might be printed material in product boxes or in ASCII or HTML on the product CD. Release notes might also become part of a product’s online documentation set if one exists.

Typically, release notes go to production for a “quick print” one to two weeks before the product is shipped. Release notes and product notes should be as short and succinct as possible.

Release notes might include the following sections:

Product notes might include the following sections:

The purpose of some demos is to provide customers with an opportunity to test that the software has been installed properly. Other demos enable a customer to see and try new features.

Demos are usually produced by engineers who write the code for the feature being demonstrated. You might be asked to review the demo, or to write one or more of the following documents:

Student guides and instructor guides are used in instructor-led training. This type of training typically takes place in a classroom with a group of students. The general editorial format of a student guide resembles the format of a hardware or software manual, except that the information is organized according to modules and learning objectives rather than by chapters.

Student guides might include the following components:

Instructor guides closely resemble student guides, except that the instructor guides contain additional directions and notes for the classroom instructor.

Other documents that are used for training purposes might include the following components: