Title PageBody of ManualAppendixes and GlossariesIndexThis chapter discusses how manuals written by Hawley & Associates employees will be organized. It is divided into four main parts:
| Title Page |
|
| Body of Manual |
|
| Appendixes and Glossaries |
|
| Index |
The Title Page contains the following elements: Title Page, Preface, and the Table of Contents.
The Title Page or Cover Page contains the manual title, part number, revision number, and date of publication just below the middle center of the page. It also lists the Hawley & Associates name, address, and phone number at the bottom center of the title page.
The Preface explains the organization of the manual and how to use it. It helps the reader decide if they are reading the correct manual. The preface should briefly describe the manual's purpose, the product the manual describes, the intended audience and what level of knowledge the readers should have before reading the manual. The preface contains the organization of the manual and a summary of each chapter in it. It also describes the font conventions used in the manual.
The Table of Contents lists chapters, sections, and subsections by number and title. The lists of Figures and Tables are considered part of the table of contents and are listed by number and title after the chapter and index (if an index is included) listings.
All manuals will have the following elements: Chapters, Figures, Tables, lists, Examples, Notes, and Warnings. Before beginning any writing, however, you should put together an outline.
An outline is the foundation for any manual. Write as detailed an outline as you can before you begin writing text. When putting together an outline, keep these ideas in mind:
Chapters are the largest divisions of the manual. They are numbered in simple numeric form and the chapter head is the first level head (for example, 1). Each chapter begins with a summary of the scope of the chapter's organization and its topics. Chapters consist of the following items: sections and subsections; and paragraphs.
A section is the second largest division of the manual. They are always numbered, being the second level head (for example 1.1). A section covers a specific subdivision of the chapter, using subsections as needed. Treat a section like a chapter by briefly explaining the scope of the section. Some sections may have information that needs to be divided further, in which case a subsection should be used. Subsection titles use third level numbered heads (for example, 1.1.1).
Occasionally, you may need to divide chapter information further; in which case a fourth-level subsection can be used. Generally, this is not encouraged unless a list, table, figure, or example can be used instead.
Each section or subsection consists of paragraphs. A paragraph is a group of sentences that support and develop a single idea or concept. A topic sentence states the major idea of a paragraph; the rest of it supports and develops that statement with carefully related details. Length should be tailored to aid the reader's understanding of ideas. Paragraph length should be just long enough to deal adequately with the subject of the topic sentence. A new paragraph should begin whenever the subject changes dramatically.
Figures, Tables and lists are all ways to make a concept easier or more memorable for the reader to understand. They also help break up white space and cut down on the number of words in a manual by explaining a concept more efficiently.
A figure is a graphic illustration of concepts, products or relationships. It should always appear before the text reference or as close to it as possible, either aligned to the left or right of the text it is referenced to, or beneath it in the center of the area just beneath the text it is referencing. It should also be referred to in text by number.
Callouts can be used when necessary. A callout identifies a certain part or area of a figure and includes a line that points to it. Use a callout to label a part, identify a setting, or to point out a feature.
When you use a figure, be sure that the reference explains to the readers exactly what they should notice. For example:
Figure 1-1 shows the Menu Bar:
Figure 1-1 Menu Bar
A table is a clear summary of information. Tables can be one page of text or several pages. Table format can vary by the type and quantity of information presented. The table name should be brief and placed below the table.
Tables should not only be introduced but explained. You need to walk the reader through an example entry showing them how to extract the information you said would be there. If you use abbreviations or symbols to save space, make sure to explain that in a legend or table notes. Here is an example:
Table 1-1 below shows the costs and other pertinent information for both prospective forklifts:
|
Max Weight |
Max |
Max Height |
Costs |
Production Stop Time |
Distance to get Repair Parts |
|
|
Electric Forklift |
1000 pounds |
30 mph |
6 feet |
Initial: $19.350 Yearly: $3100 |
3 days |
500 miles (next day delivery) |
|
Gas Forklift |
2000 pounds |
40 mph |
12 feet |
Initial: $20,670 Yearly: $2,800 |
2 days |
17 miles (same day delivery) |
Table 1. Gas and Electric Forklift Comparisons
Lists are useful for breaking up white space and for emphasizing information. If you are writing a sentence with more than three serial commas, you probably should display it in a list. Try not to break lists across pages. There are three types of lists:
An example shows the reader an instance of a concept to help make it easier for them to understand. It should always have a 2.5 inch indent from the left, as follows:
When you want to change terminal emulation, type: %set env
A Note draws attention to important information that is either not covered in the text or is a special variation of information covered in the previous paragraph. For example:
Note: Release 4.5 and below of Fortunit Software has this feature disabled.
Notes should always have a 2.5 inch indent with the word Note in Bold text.
A Warning draws attention to a potentially hazardous condition or problem. For example:
Warning: Do not attempt to reboot the system in event of a power failure.
As with Notes, Warning messages should always have a 2.5 inch indent with the word Warning in Bold text.
The Back Matter of all manuals contain the following elements: Appendixes, Glossary, and an Index. The Index is covered in the next section of this chapter.
Appendixes contains supplementary information. This is where an appendix differs from a regular chapter. For example, your manual may have a chapter on common system commands and what they mean, but you will also have an appendix to list less common or rarely used system commands. Another use for appendixes is for detailed product specifications or for system error messages.
Rules for writing appendixes are the same as for chapters. Each appendix begins with a summary of the scope of its organization and its topics All elements used in chapters can also be used in appendixes. All appendixes must be referenced within the body of the manual.
A glossary is an alphabetical list of words, acronyms, or other terminology used in a manual. It is an optional element, but we recommend one for any document written to audiences unfamiliar with the subject matter.
The Index is an alphabetical list of topics with the page numbers where they appear in a manual. It is one of the last processes involved with producing a manual. We recommend including an index for any manual over ten pages in length.
An index contains three major parts:
Economic costs. See Benefit-cost analysis.
Technical Writing. See also Manuals.
Do not attempt to compile an index until the final manual is completed because the topics and page numbers will change constantly while a work is in progress. The best way to compile a list of topics is to read through the manual from the beginning, each time a key term appears in a significant context, list the term and its page number on either a 3X5 card (if done manually) or make a notation in whatever indexing software you are using in conjunction with writing of the manual.
The key to compiling a useful index is selectivity. Do not list every reference to a topic. Instead, select references to passages where the topic is discussed fully or where a significant point is made about it.
For actual index entries, choose words or phrases that best represent the topic. Topics can include:
When you create the index, start by doing a "draft index." That is, create the major headings, adding subentries as you go with the intent of just gathering the major topics. Print out your draft. This makes it easier for you to remember what topics you have already selected and it makes subentries easier to organize. Then go through a second and third time as needed, revising and adding entries and subentries as needed.
The first word of an index entry should be the first word because the reader will look for topics alphabetically by their main words. Selecting the right word to list first can be difficult; some topics are easier to list than others. For example, tips on repairing electrical wire would not be a good index entry, because the reader would not look under the word tips. However, if you create an index entry called Electrical wire with a subentry called repairing, it would tell them where they would find out how to repair the electrical wire.
If you are using Word 95/98, you can also use the Search and Find and Search and Replace features to create index entries.
In Styling the index, follow these rules:
Newts, history, 15 species, 19