Many different types of technical documents exist. These documents can range from a single-chapter manual, such as a white paper or simple installation guide, to a highly technical user’s guide or training manual. Documents can also be part of a documentation set that contains several documents.
This chapter discusses the following topics:
“What Is a Documentation Set?” on page 169
“Documentation Plans” on page 170
“Abstracts” on page 172
“Structure of Manuals” on page 172
“Descriptions of the Manual Parts” on page 174
“Types of Hardware Manuals” on page 178
“Types of Software Manuals” on page 180
“Other Product Documents” on page 181
“Training Documents” on page 184
A documentation set includes one or more types of documents that a customer receives with a product. A typical documentation set might include the following:
Manuals
Textual pieces of a CD-ROM package
Online help
Release notes
Other related documents, such as white papers
If you work at a large company, you might create or update a specific document, such as a user’s guide or reference manual. In smaller documentation groups, a writer might work on all parts of the documentation set, including planning documents. The following sections describe the parts of a documentation set.
Publications groups often use planning documents to describe the contents and packaging of documentation sets and the individual documents within these sets. You can also use planning documents to describe individual documents.
Your involvement in the creation of planning documents depends on the scope of the project and your position within the writing team.
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.
Use a documentation set plan template when you create a new set of manuals. The plan template might include the following:
Structure of the set
Audience description
Document content plan, for each document in the set
Documentation schedule
Reviewer list
Roles and responsibilities of publications members and product team members
Issues, including decisions that have not been made or known problems
Dependencies that must be met for the project to be successful
Localization plans
Related documentation efforts
Competitive analysis
Publications quality assurance plan
Media formats, such as print and online
Format of the set, including bindings, cover type, and other items
Packaging plans
Use a documentation set revision plan template when you update one or more manuals that are part of a set or when you add or delete one or more manuals from a set. The plan template might include the following:
Structure and delivery, including differences from the previous set
Documentation schedule
Reviewer list
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.
Use a document plan template when you create a new, standalone manual that will not be part of a documentation set. The document plan template might include the following:
Content outline
Audience description
Manual schedule
Reviewer list
Roles and responsibilities of publications members and product team members
Issues, including decisions that have not been made or known problems
Dependencies that must be met for the manual to be effective
Manuals that will be referenced from this document
Localization plans
Publications quality assurance plan
Media formats, such as print and online
Format of the manual, including size, cover type, and similar details
Packaging plans
Related documents
Competitive analysis
Use a document revision plan template when you revise an existing standalone manual that is not part of a documentation set. The document revision plan template might include the following:
Content outline
Manual schedule
Reviewer list
Related documentation
Structure and delivery of the revised manual
An abstract conveys to potential readers what is in a book so that they can make an informed decision about whether to read the book. When writing an abstract, reduce text to a few sentences and to no more than two paragraphs. Use the appropriate trademark symbols where necessary.
Typical technical manuals might consist of either a single chapter or multiple chapters.
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:
Simple installation manuals
Release notes
Product notes
White papers
Note — Release notes require special consideration. See “Release Notes and Product Notes” on page 183 for more information.
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.
Table 9-1. Possible Components of Manuals With a Single Chapter
Part of the Manual | Requirement |
---|---|
Title page | Required. |
Legal notice | Required. |
Table of contents | Optional. |
List of figures | Optional. Helpful if many numbered figures are used. |
List of tables | Optional. Helpful if many numbered tables are used. |
List of examples | Optional. Helpful if many captioned examples are used. |
Chapter | Required. |
Index | Recommended if the chapter has more than 20 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.
Table 9-2. Possible Components of Manuals With Multiple Chapters
Part of the Manual | Requirement |
---|---|
Title page | Required. |
Legal notice | Required. |
Table of contents | Required. |
List of figures | Optional. Helpful if many numbered figures are used. |
List of tables | Optional. Helpful if many numbered tables are used. |
List of examples | Optional. Helpful if many captioned examples are used. |
Preface | Required. |
Part I | Optional. Use a Roman numeral. |
Chapter table of contents | Optional. |
Chapters | Required. |
Part II | Required if a Part I is used. |
Parts III and higher | Optional. |
Appendixes | Optional. |
Glossary | Optional. |
Bibliography | Optional. |
Index | Recommended for manuals that are longer than 20 pages. |
This section describes the general editorial formats of the parts of a typical manual. The parts are listed in the order in which they usually appear within a manual.
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 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:
Who Should Use This Book. Describe the audience or class of reader for whom the manual is intended. The audience description might include the following information:
Required knowledge, such as a specific programming language
Required experience or familiarity with the software or hardware platform
Definition of the type of user or functional responsibility, such as applications programer, system administrator, or field engineer
Terms that relate to the tasks the user might perform
Before You Read This Book. If this manual requires that the user read other documents before effectively using this manual, list those other documents.
How This Book Is Organized. Briefly describe the contents of the manual. Consider using a live cross-reference to list each chapter and appendix.
Related Books. List titles of internal documents that are related to the manual. Also list third-party books, and their authors and publishers, that are mentioned in the text or that readers might find useful.
Accessing Documentation Online. Inform readers how to view documents online if your company provides this service.
Typographic Conventions. List and explain special symbols, characters, or typography that are used in the manual.
The three general types of chapter page numbering and heading styles are:
Single. Single chapters are not numbered. There is no chapter number, first-level headings are not numbered, and the page numbers run sequentially starting from 1. This format is used only in manuals with one chapter. See “Manuals With a Single Chapter” on page 172.
Multiple, unnumbered. The chapters are numbered, but the headings are not. Pages are numbered sequentially, starting from 1, or pages can be numbered sequentially within each chapter, starting from 1-1.
Multiple, numbered. The chapters are numbered, the first-level headings through the third-level headings are numbered, starting from 1.1. Pages are numbered sequentially within each chapter, starting from 1-1.
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:
Long programming code examples
Long lists, charts, and tables
Summary information, such as a list of a program’s function keys
Technical specifications
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:
At the end of the manual, following the last appendix
At the end of the manual, following the last chapter if the manual contains no appendix
Before a bibliography or index
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.
This section briefly describes some of the types of manuals that are typically written for a hardware product. Some of the different types of hardware manuals include the following:
Installation
System overview
User’s guide
Service
Configuration
Specification
Site planning
Troubleshooting
Getting started
In general, there are two types of installation guides:
System installation guides for workstations, servers, and external expansion systems
Internal installation guides for field-replaceable units (FRUs) inside systems
The FRUs could include subsystems (mass storage systems and switches), individual devices (drives), components (CPU modules and memory modules), and chassis units (fan trays).
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.
This section briefly describes some of the types of manuals that you might write for a software product. Software documentation typically includes the following types of manuals:
Installation
Programmer’s guide
System administration
User’s guide
Reference
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.
Though manuals form the bulk of typical technical documentation, you might also find yourself writing other types of documents. Some of these documents could be considered manuals, but their uniqueness demands special consideration.
These documents include the following:
White papers
Online help
CD text
Release notes and product notes
Demos
Road maps
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:
CD faceplate text
Text insert
The CD faceplate text appears on the disc faceplate and typically includes the following information:
Product title
Hardware platform supported
Operating system and other software compatibility
Applicable legal notice and third-party trademarks
File system format
File system format refers to the file system structure of the software on the disc. An example is MS-DOS format.
The CD text insert is a glossy paper brochure that forms the cover text for the CD-ROM package. The CD text insert typically consists of a title page, legal notice, and textual information.
Information that you supply on the title page template typically includes the product title and hardware and software platforms supported. The legal notice provides the applicable trademarks and third-party trademarks for the product, consistent with the legal notice for the documentation set.
The content and length of the textual information for the brochure can vary. The textual information typically includes a brief description of the product and might also include instructions for mounting the CD.
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:
Title page
Legal notice
Table of Contents
Preface
Installation Bugs
Runtime Bugs
New Features
End-of-Support Statements
Driver Updates
Patches and CERT Advisories
Documentation Issues
Product notes might include the following sections:
Title page
Legal notice
Table of Contents
Preface
Getting Help
Compatibility
Known Problems With the Hardware
Known Problems With the Software
Documentation Issues
Bugs Fixed Since the Last Release
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:
README file
Instructions for loading and running the demo
An explanation of what the demo is intended to illustrate
Training documents are yet another type of technical documentation. Training documents vary widely in format, style, and delivery method, depending on how they are used. For example, a training document that an instructor uses in front of a classroom is different from a training document that a student accesses over the Web for self-paced learning.
Typical training documents include the following:
Training materials for use in instructor-led courses that are delivered in classrooms
These materials might include a student guide, an instructor guide, which consists of the student guide plus additional notes, overheads, workbooks, and study guides.
Training materials that are delivered on a CD that uses proprietary software
Training that is delivered over the Web and that uses multimedia capabilities
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:
Title page
Legal notice
Table of Contents
Preface
Modules
Labs
Exercises
Appendixes
Index
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:
Study guides
Student workbooks
Lab manuals
Certification exams
Video or audio presentations
Technology-based training (TBT) delivered on CD
Classes accessed on the Web
Consulting materials, such as skills assessments or white papers
18.117.71.211