DOCUMENTATION & PROCEDURES MANUAL SEMINAR
I. INTRODUCTION
II. WHAT IS DOCUMENTATION?
Why Is It Necessary?
Threats To The System Without Documentation
Vendor User Manuals
III. TYPES OF USER MANUALS
Questions to be Asked Regarding User Manuals
Contents
Formats for Preparing User Manuals
Caption
Playscript
Matrix
Flowcharts
Narrative
IV. GUIDELINES TO GOOD MANUAL WRITING
V. CONCLUSION
VI. QUESTIONS AND ANSWER PERIOD
II. WHAT IS DOCUMENTATION?
Documentation is written information about computer hardware and software. It may consist of the following:
Instructions
Training manuals
On-screen tutorials
Comments in programs
Reference materials
WHY IS IT NECESSARY?
Documentation is necessary because:
It supports management decision-making through the provision of timely and accurate information
It provides for integrity of system independent of people
It establishes audit trails; which are always requested by the auditors
It controls system conversions & upgrades
It serves as training tools
It provides for a reference manual for non-routine functions
It insures proper installation of a new system or upgrade:
• by computer staff and department heads
• by End-User
It instills confidence in the computer system
THREATS TO THE SYSTEM WITHOUT DOCUMENTATION
Without documentation or office procedure manuals the following usually occurs:
Lack of continuity because of personnel turnover
Lack of standardization
Possibility of incorrect instructions being imparted
Loss of productivity
Loss of time through trial and error
Loss of efficiency and integrity of information
High-level people doing low-level work
Loss of employee morale
VENDOR USER MANUALS
Most data processing documentation prepared by software companies is a combination of "sales pitch" and computerese intended for the technical staff and the extremely knowledgeable individuals only;
CERTAINLY NOT FOR THE END USER
WHY?
User Manuals are the lowest priority
In many cases not included in the package
Most programmers detest preparing documentation
Most programmers assume too much!
III. TYPES OF USER MANUALS
1. Office Procedure Manuals (paper work flow)
2. Computer input/output documentation
3. Miscellaneous training tools: graphic or matrix
QUESTIONS TO BE ASKED REGARDING USER MANUALS
• Is terminology easy to understand?
• Does it include:
o Step-by-step instructions?
By prompt, if computer documentation
By function or task I if office procedures
o Easy to find contents?
CONTENTS OF A MANUAL
Cover Sheet
Overview
Index
Glossary
How-To Section
Menu
Numbered procedures for each program
Sample reports
Support Files
Charts, other exhibits
FORMATS FOR PREPARING USER MANUALS
1. Caption
2. Playscript
3. Matrix
4. Illustrations*
5. Flowcharts*
6. Narrative**
- Usually used to support other methods
- Narrative preparation of documentation or office procedures is the most likely NOT TO BE READ OR USED!
CAPTION FORMAT
SUMMARY Main groups of information are high-lighted by a key word. A brief narrative then expands on the topic.
The key word, or “Caption” is located on the left margin; it is typed in capitals for quick identification. Narrative is typed an inch or two to the right. Note that the length does not exceed about 4 1/2 -5 inches. This makes for easy reading.
ADVANTAGES Fast retrieval of information
Saving in “Read Time”
Easier understanding
Attractive and easy to read, due to ample use of “White Space”
EXAMPLE This procedure has been written in Caption Method; and can be used for any manuals material
PLAYSCRIPT FORMAT
The Playscript Method:
Used for sequential routines, which may move back and forth between two or more people.
Called Playscript because it lists the 'Actors' sequentially, as they are required to perform their duties.
This layout explains WHO (Job Title) DOES (Action Word) WHAT (Actual Function)
Tells only how to proceed -omit other matter
Identify the ACTORS -the people in the organization WHO do the 'Actions'
Write in a logical time sequence, starting with first action and continuing to last. Number each step. Continue numbering regardless of changes of ACTOR.
Start each sentence with a verb: Prepare, Send, Contact, etc.
Use plenty of 'White Space' so that ACTORS are easily identified, along with WHAT they have to do.
Use simple words and short sentences
MATRIX FORMAT
The Matrix Method of writing procedures:
Used when action depends on variables
Arranges detailed narrative in rows and columns
Shows rules and conditions which must be met before any action is taken
Keep as simple as possible
Take time to do a good 'drafting job' –remember that a matrix is more an illustration than a narrative statement
Make lines clear, with heavier lines for major divisions
Locate 'Answers' towards right and/or towards bottom whenever possible
NOTE: Try to avoid 'Sideways' or vertical printing, as this increases reading time.
IV. SOME GUIDELINES TO GOOD MANUAL WRITING
1. Write in a natural manner
2. Write with nouns & verbs (avoid too many qualifiers)
3. Don't over-write (or overstate)
4. Avoid acronyms & abbreviations
5. Don't take shortcuts at the expense of clarity
6. Avoid fancy words
7. Avoid foreign language expressions and “off-beat” phrases not understood by everyone
8. Don't inject opinions
9. Avoid sexist language
10. Revise and re-write over and over again
11. Keep the reader in mind – Prepare the manual for a "TEMPORARY" person hired for the day or the project
V. CONCLUSION
Approach In Preparing Documentation Or Procedure Manuals:
Involve the USER
Think as a USER
Debug by proceeding through every programming step
Follow 11 points to “Good Manuals Writing”
Be a USER!
KISS (Keep It Simple Stupid)