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)

  • No labels