In Part 1, we covered Preparation and the Writing Process.
Part 2 includes:
· The first draft
· Document production
· Editing & proofreading
· Reviewing & fieldtesting
· Production
· On-line documentation
· Maintenance
Before beginning the first draft, make sure the preparations discussed in Part 1.
If you follow these steps, your documentation will comply with the IEEE Standard 1063 (1987) which relates to software user documentation. Include all of them unless they specifically do not apply.
Prepare a documentation project plan according to the details specified in Section 2 - Preparation.
Briefly this includes the following:
· Identifying the software.
· Determining the software audience.
· Determining the document set.
· Determining the document usage mode
- Instruction mode
- Reference mode
This section outlines the information required to be shown in user manuals generally. The eleven basic components of a software user document are as follows:
1. Title page
2. Restrictions
3. Warranties
4. Table of Contents
5. List of Illustrations
6. Introduction
7. Body of Document
8. Error Conditions
9. Appendixes
10. Bibliography
11. Glossary
User Documentation Inclusion Requirements
Component 8 Pages or less > 8 Pages First Vol. Other Vol(s)
Title page M M M M
Restrictions M M M M
Warranties R R R R
Table of contents O M M M
List of illustrations O O O O
Introduction
Audience description R M M R
Applicability M M M M
Purpose R M M R
Document usage R M M R
Related documents R R R* R
Conventions M M M R
Problem reporting R M M R
Body
Instruction mode 1 1 1 1
Reference mode 1 1 1 1
Error conditions R R R R
Appendixes O O O O
Bibliography M M M** M**
Glossary M M M** M**
Index 2 2 M** M**
M = mandatory, O = optional, R = make reference, * = should address relationship in other volumes, ** = mandatory in at least one volume of the set, with references to information in other volumes. 1 = Every document has a body, 2 = index is mandatory for documents larger than 40 pages.
The titles used in this section are general and are not intended to be prescriptive; for example, `audience description' need not necessarily be labelled as such.
1. Document title (i.e. XYZ User Guide).
2. Project name (if applicable).
3. Document identification number (if applicable).
4. Version number (if applicable).
5. Approval information.
6. Optional details for the commissioning and/or accepting of the document.
7. Release date - the date the version number was last changed.
8. Status - whether `draft' or `approved'.
9. Copy no. - controlled/uncontrolled copy.
10. Company/organisation logo as specified by your organisations policy on how to display logos on printed material.
+ Note: Header/footer is not displayed on the title page.
The page following the title page should contain the following information:
· Document information - including the organisational unit which produced the document, the project manager's title, name, telephone and fax numbers.
· Authors name - include mention of the people involved with the preparation of the manual. Those who helped with advice or with some other kind of help. If the work is anonymous, users won't know who to consult on matters relating to the manual.
· Revision history - including at least version number, date issued, author and comments regarding the purpose/updates contained in that version.
· Include mention of the software packages used to produce the manual, i.e. Word for Windows (V6.0). This may be useful information later when upgrades or additional manuals are necessary.
· Copyright notice.
A table of contents is mandatory for every document greater than eight pages in length.
For single-volume documents this requirement should be met in one of two ways.
· Comprehensive table of contents for the whole document.
· Simplified table of contents, with a comprehensive section table of contents preceding each section.
For multi-volume documents (i.e. a single document in multiple volumes), meet this requirement by including a simple table of contents for the entire document in the first volume. In additional, each subsequent volume should contain either of the following:
· Comprehensive table of contents for the whole volume.
· Simplified table of contents for the volume, with a comprehensive section table of contents preceding each section.
Construct a comprehensive table of contents for a complete document or for a section in the following way.
· Carry entries to at least the third level of the document structure hierarchy.
· Page numbers given for each entry and are joined to the entry by a leader string (row of dots) as seen in this manual's table of contents.
In a simple table of contents include at least the first level of the document hierarchy with the corresponding page number.
User manuals may include a list of illustrations, or separate lists for different illustration types (i.e. tables, figures etc.). If included, list(s) of illustrations should appear immediately after the contents list and should contain the following:
· Titles of all illustrations included in the document.
· The page numbers for each entry, joined to the entry by a leader string (row of dots).
Choose whether to have separate or merged lists. The type to use depends on how easy it is to understand the resultant list(s).
· Merged list - the list can be merged into one where only a few different illustration types are concerned.
· Separate list - can be used to distinguish figures, tables, screens etc. where there is a significant number of each illustration type.
· Header contains the document ID number (refer section relating to title page), status and document version.
· Footer contains, from left to right, the project name, document title and page number.
· Both header and footer to use Arial 8pt normal.
· Header to have a narrow ruling line below and the footer a similar line above.
The following information should be given in the introduction.
· Audience description.
· Applicability statement.
· Purpose statement.
· Document usage description.
· Related documents list or information.
· Conventions description.
· Problem reporting instructions.
The sections which follow describe these elements in detail.
Describe the intended audience. If different sections or volumes in a set for different audiences, indicate the intended audience for each section.
In the audience description, indicate the following:
· Experience level expected of the user.
· Previous training expected of the user.
A description of the intended audience lets the read decide whether to read any further.
Specify the following:
· Software version being documented.
· Hardware /operating system environment under which the software runs.
Explain why the software was written and summarise the purpose of the software. Include typical intended uses of the software.
Describe the contents of each section, its intended use and the relationship between sections. Also provide any other directions necessary for using the document.
Example:
The manual is divided into three sections:
Section 1 Debtors Ledger used by accounts staff and management in the day to day processing of accounts receivable. Section is divided in seven sub sections which give full detail of the seven main functions.
Section 2 Creditor's Ledger used by staff in the processing of accounts payable. Section is divided in six sub sections.
Section 3 General Ledger used by staff to operate the general ledger. Section is divided in twelve sub sections.
List related documents and give their relationship to each other. If the user documentation is made of many volumes, this `related document' information can be provided in a separate document called a `road map' or guide to document set.
Example:
Other documents relating to the XYZ Accounting Software User Guide include:
Training Guide - a set of practical hands-on exercises.
Quick Reference Guide - essential information on a laminated card.
The related documents are designed to complement not replace the user guide.'
Summarise symbols, stylistic conventions and command syntax conventions used in this manual.
· Symbols - describe each symbol and how they are used in the document. (i.e. `In this manual, important points are emphasised with a heavy arrow as follows: è`)
· Style - explain any stylistic conventions with which the reader may be unfamiliar. These include conventions such as highlighting, boldface or italic script to indicate specific meaning. (i.e. `When a special term is first used, it is shown in boldface. Chapter names, menus and keyboard commands also appears in boldface when they are used in the context of performing an action.')
· Command Syntax if applicable, describe command line conventions and include examples. (i.e. `Command line entries appear in Courier boldface, i.e. XCOPY C:\SAMPLE\*.* A: /S')
Give the reader instructions on the following:
· How to report software problems.
· How to contact the help desk (If applicable).
· How the reader can submit suggestions for changes in the software or the document.
List the name and contact information for the organisation responsible for responding to the problem reports or suggestions for improvement.
Determine the content, organisation and presentation of the body of the document after determining whether the document is an instructional mode or reference mode document. In either mode, use a consistent organisational structure based on the expected use of the document, providing examples where necessary.
Information-oriented instructional documents give the reader background information or theory needed to understand the software. Include a scope as defined below before giving the information forming the major portion of the document. Use topics to organise an information-oriented instructional document. For example, the document could be organised as follows:
· Theory.
· Software features.
· Software architecture.
Task oriented instructional documents gives the reader the necessary information to do a specific task or attain a specific goal. Provide all of the information listed below relating to scope, materials, preparations, cautions/warnings, method and related information. Use task relations to organise a task-oriented document or section (i.e. Organise by task groups or task sequence).
Scope Begin this section by indicating to the user the scope of the material to be discussed.
Materials Describe any materials the user will need to complete the task (i.e. input manuals, passwords, computers, peripherals, cabling, software drivers, interfaces and protocols). Alternatively, describe separately the materials common to all or many functions and refer to that description.
Preparations Describe any action, technical or administrative, that should be done before starting the task (i.e. obtain system passwords, access authorisation, disk space). Alternatively, describe in a separate section the preparations common to all or many functions and refer to that section.
Cautions and Warnings Describe general cautions and warnings that apply to the task. Place specific cautions and warnings on the same page and immediately before the action that requires the caution or warning.
Method Describe each task, including the following:
· What the user should do
· What function, if any, is invoked, (including how to invoke the function and how to recognise normal termination).
· Possible errors, how to avoid them and how to solve them.
· What results to expect.
Related Information Provide other useful information about the task, including the following:
· Tasks frequently performed together and their relationship.
· Other tasks customarily performed by the users of this document that could be supported by the methods of this section. Describe this support.
· Notes, limitations or constraints (notes may also be placed in the specific area to which they apply).
Organise a reference mode document the way a user accesses a software function. Methods include the following:
· By command
· By menu selection
· By system calls
Within this organisation, arrange the functions for easy access and random user access (i.e. alphabetical order or a menu-tree hierarchy). For each function, include all of the information listed below relating to purpose, materials, preparations, inputs, cautions/warnings, invocation, suspension of operations, termination of operations, output(s) error conditions and related information.
Purpose. Describe the purpose of the function.
Materials. Describe any materials the user will need to complete the task (i.e. input manuals, passwords, computers, peripherals, cabling, software drivers, interfaces and protocols). Alternatively, describe separately the materials common to all or many functions and refer to that section.
Preparations. Describe any action, technical or administrative, that should be done before starting the task (i.e. Obtain system passwords, access authorisation, disk space). Alternatively, describe in a separate section the preparations common to all or many functions and refer to that section.
Input(s). Identify and describe all data required for the correct processing of each function. Use one of the following methods.
· Describe inputs used only by a single function in the section devoted to that function.
· Describe in a single section or in an appendix inputs used by multiple functions. Refer to that section or appendix when describing these functions.
Cautions and Warnings. Describe general cautions and warnings that apply to the task. Place specific cautions or warnings on the same page and immediately before the action that requires the caution or warning.
Invocation. Provide all information needed to use and control the function. Describe all parameters. Include the following:
· Required parameters
· Optional parameters
· Default options
· Order and syntax
Suspend Operations. Describe how to interrupt the function during execution and how to restart it.
Termination of Operation. Describe how to recognise function termination, including abnormal terminations.
Output(s). Describe the results of executing the function, for example.
· Screen display.
· Effect on data or files.
· Completion status values or output parameters
· Outputs that trigger other actions (i.e. mechanical actions in process control application.)
Provide a complete results description for each function. If several results are possible, explain the situations that produce each.
Error Conditions. Describe common error conditions that could occur as a result of executing the function, and describe how to detect that the error has occurred. For example, list any error messages displayed by the system. (Error recovery need not be included here if they are covered in the later section `Error messages, known problems etc'; - see below)
Related Information. Provide other useful information about the task, including the following:
· Tasks frequently performed together and their relationship.
· Other tasks customarily performed by users of this document that could be supported by the methods of this section. Describe this support.
· Notes, limitations or constraints (notes may also be placed in the specific area to which they apply).
Provide a list of error messages in a convenient location, i.e. in a separate section, chapter or appendix.
A complete error message index includes the following:
· A list of each error message and/or code with an explanation for each.
· The error that caused it.
· How to recover from it.
· The action(s) needed to clear it.
· Describe known software problems here or in a separate document and provide alternative methods or recovery procedures.
Include in appendixes any material which supports or augments the information given in the main part of the manual. The list that follows is exhaustive and some points may not apply except in highly complex and/or technical situations.
· Input and output data or formats which are used in common by a group of functions.
· Input and output codes (i.e. inventory codes).
· Interactions between tasks or functions - i.e. a description, illustrated with diagrams of the relationships and interaction between groups of tasks or functions.
· Global processing limitations if applicable.
· Description of data formats and file structures.
· Sample files, reports or programs.
If applicable, provide a list of any publications that may have been quoted or referenced in the manual. Where applicable, other sources containing related information can also be included to point a curious reader in the direction of further information.
The bibliographic entry includes:
· Author's name and initials.
· Year of publication
· Title in italics.
· Publisher's name.
· The second and subsequent lines are indented.
List alphabetically in the glossary definitions of the following:
· All terms, acronyms and abbreviations used in the manual with which the read may be unfamiliar.
· All terms, acronyms and abbreviations with which the reader may be unfamiliar (i.e. the way in which they are used or their context).
Development an index, based on key words and concepts, for any user document greater than eight pages in length.
Construct the index as follows:
· Indicate the importance of information, place minor keywords under major ones. (i.e. `Printer' could be further divided into cabling, connection to, error messages and fonts).
· Give the page location to the right of each entry.
· List location references in one of the following ways:
- By page number
- By section or paragraph number
- By illustration number
- By other index entry
· Use only one level of index entry. Where an entry points to a second index entry, the second entry should give the location and not point to a third entry.
The document presentation requirements are outlined in detail in section 5 of this guide.
The following are general guidelines:
Use terminology and typographic and stylistic conventions consistently throughout the document or set of documents. Identify any deviations the first time they appear.
Define all terms requiring a glossary entry, acronyms and abbreviations when they appear for the first time. This means the glossary appears twice; once in a section of it's own and again distributed throughout the text as the term is used for the first time.
If related material is placed in separate parts of the document, or in separate documents of a set, repetition of the information can be avoided by providing specific references to the related information.
This-version function changes
Software changes made while documentation is being written which need to be reflected in the documentation. There need to be a process by which changes in the functionality of the software being documented are made known to you so that they may be reflected in the documentation.
This procedure often involves the documenter receiving a copy of the software change control form which details the nature of any changes made.
Changes in the functionality of the software which are made while the documentation is being written but which are not to be reflected in the documentation on publication. The changes will be reflected in subsequent publications.
The distinction between `this-version' and `next-version' is usually made on the basis of a cut-off date - i.e. any changes after an agreed date will go into the next version.
Return to Technical Communication Resources Page | Return to CIT Home Page