Every good manual is like a good book, or a good film. Remember what your teacher told you about writing a story; it must have a beginning, a middle, and an end.
The beginning, middle and end of a manual have specific names:
Front matter is the beginning.
Body is the main manual content.
Back matter is the stuff at the back.
Front Matter
The front matter has a number of parts, depending on the size, purpose, scope and intended audience. You should consider the following parts in the front matter:
The title page is the main facing page inside the cover, or it may be the cover. It's usually simple and straightforward, with a pleasing graphic design. It should be easy to recognise the manual from its title page.
The title page should include:
The title, preferable naming the product and type of manual
This page is usually inside the cover or on the back side of the title page.
It contains all the legal information and the copyright on the manual. It may also have the library reference details, contact details for the publisher, and also the ISBN.
The table of contents is the main navigation aid for the reader. It allows easy access to sections, chapters and topics by page number or hyperlink.
The table of contents is also the may most readers assess if a manual is likely to be useful for a specific task. Don't use obscure or smart chapter names just to be creative.
It's not unusual to now have a summary table of contents first, followed by a detailed table of contents over several pages.
Always consider the readers needs when deciding what to show, and how to present the table of contents.
If the reader is likely to want to look up diagrams, charts or graphics for specific tasks then you should consider a list of figures. However, if the figure captions are going to replicate the chapter or topic names then there is not much point having a list of figures.
If the reader is likely to want to refer to specific tables to achieve a task then consider having a list of tables in the front matter. However, if the name or caption on the tables replicate the chapter or topics names then there is not much point producing a list of tables.
In some reference guides or training manuals, a list of examples may be a useful access path for the reader. If the example names only replicate the chapter or topic names then this list does not add much value.
The preface is very important; to the reader and to the communicator.
For the reader, the preface states the who, why, and how of the manual. A good preface states clearly:
who the intended audience is
what the scope of the manual is
how the manual is to be used
how the information is organised
what other relevant documents exist
what typographic conventions are used.
As a communicator, you will want to assume that readers read the preface; very often they don't.
Producing a preface at the start of developing a manual is very important, especially if you don't bother to develop a formal information plan. A draft preface provides focus and documents the purpose and intended audience.
Don't make the preface into and Introduction chapter, and don't think that having an Introduction means that you don't need a preface.
Body or Chapters
The body of the manual usually consists of chapters. If the manual is large, the chapters may be grouped into sections.
The size, shape, structure and order of the body of the manual must be based on the purpose and intended usage. A training manual would have a totally different structure to a user guide, and different again to a reference guide.
Some manuals, such as reference guides, are not structured in chapters. The consist of large numbers of small topics, arranged in alphabetic order. A data dictionary is an example of a reference manual that would not need chapters or sections.
Back Matter
The back matter also has a number of parts, depending on the size, purpose and scope. There are two considerations in deciding what to include: does the reader need help to use the manual, does the reader need additional information.
The appendices are supplements to the main content of the manual.
There is one reason for putting content in an appendix instead of in the body chapters: the material is important and relevant, but not within the strict intended usage of the manual. For instance, a training manual may need reference tables or command summaries.
The appendices let you include relevant supplementary information while still sticking to the terms of reference laid out in the preface.
Resist the temptation to dump extra content into appendices, just because it needs to go somewhere. If it doesn't add value to the reader, leave it out.
A glossary is an alphabetic list of defined terms, phrases, abbreviations and acronyms. It's always a reference section; you should never assume that the reader will read it. They will only read it if they need to. Make sure you tell the reader that there is a glossary by listing it in the table of contents and mentioning it in the preface.
The glossary entries define and explain key concepts as used in the manual. This means that you must use the term consistently throughout the whole manual.
The bibliography lists the sources of documents used in compiling the manual which you refer to. There are strict conventions on the format and content of bibliographies. You should choose one of the recognised standards and use it consistently.
Resist the temptation to list references to impress the reader. Only include a bibliographic reference if:
you are legally obliged to acknowledge the source of information used, or
the reference material will significantly assist the reader achieve a goal within the purpose of the manual.
The decision to build and include an index should not be taken lightly. Be very clear about why the reader needs an index and how it will be used.
Building a full, useful index of a substantial manual is a large task. It will add a major overhead to the project. In a reference manual you may be able to avoid building an index by arranging the topics alphabetically in the body of the document. A training manual may not need an index because it is not intended to be used as a reference guided.
Resist the temptation to think that online searching obviates the need for an index. A good index will provide references to common synonyms that the reader may want to search on. For instance, a computer user manual may describe the exit command; the index would have an entry for quit. A search facility, by itself will not locate the exit command when the reader searches for 'quit'.
Title Page