Structure
Good organization goes a long way towards creating good documentation. You need to consider the type of manual that you want to create before you start work. Not every manual can follow the same structure. You must break up a complex, multifunction application such as Evolution into many parts, to provide detailed explanations of the separate functional modules. An applet, on the other hand, needs a brief description of the GUI, basic usage instructions, and details on any necessary preferences.
- 1.5.1. Help Manuals
- 1.5.2. Guides
1.5.1. Help Manuals
Wherever possible, use templates to ensure that your Help manual follows a standard approach. You can find templates for Help manuals in the http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/.
1.5.2. Guides
If you need to write a guide about a large application or a set of applications, then the book is substantially longer than a Help manual. You need to develop an outline plan for your guide. The precise composition of your manual depends on the subject, however in general you need the following book components:
- Front matter
-
Defines the function of the book. Includes navigation aids to the remaining sections of the book, such as a table of contents, or links. This section might contain a Preface.
- Introduction
-
Explains the application to new users. You should provide an expanded definition of the function of the application, built around illustrations and examples.
- Document body
-
Consists of several sections or chapters that provide a more detailed explanation of how to use the application. This is where you achieve completeness, telling the user how to complete all the main tasks associated with the application. Chapter headings are usually descriptive of the each topic area. Sub-headings within the chapter are usually task-oriented, so that users can quickly find information about a specific action within the topic area.
- Glossary
-
Defines specific terms in the book. You do not need to define terms that are in the http://www.bartleby.com/61/.
- Appendices
-
Contain additional notes about related topics that are not directly explained in the document body.
- Index
-
Provides keyword links to specific concepts in the book. Follow the guidelines in this guide to create an effective index.