CSE1IS Information Systems Week 12 Lecture 1 System Documentation

1. Introduction

• Preparing documentation is an important but frequently overlooked activity during systems implementation. Documentation provides information to users on how to operate and maintain a system. Documentation also provides information needed for future modifications or reimplementations.
• Any substantial information system project will generate a great deal of documentation. The text  (pp. 434-440) identifies four major types:
• program documentation, system documentation, operational documentation and user documentation.
• Each type of documentation is written for a particular 'audience'

1.1 Program documentation

• includes the software design documents, the test plans, the test data and testing results.
• It is intended for use by systems professionals (including programmers) as they attempt to understand how the current system operates or attempt to identify areas for system maintenance.

1.2 System documentation

• includes the documents that are generated by systems professionals throughout the IS project.
• Components include the requirements report, the design specification, DFDs, ERDs, the system dictionary, database design, etc.
• Program documentation could be viewed as a subset of this.
• In general system documentation is directed towards system professionals who are attempting to understand how the current system was developed and how it was designed to operate.

1.3 Operational documentation

• is designed for the people who are running and maintaining the system while it is in production i.e. the operators in the computer centre.
• It tells the operations group when and how to run the programs in the system, when and how to run the back-up procedures, provides advice on system recovery when a problem occurs, provides detail for error messages etc.
• It should be noted that many operational tasks today are automated.

1.4 User documentation

• tells a user how to use the system. It may also provide some user training material. User documentation is non technical and directed to a system user rather than a computing professional.
• Rapid technology changes have altered the nature of documentation. In the past most documentation was printed on paper and organized into bound or loose-lesf books.
• Automated documentation is now the norm and formats include the following:
  • Electronic documents, such as documents stored in Microsoft Word or Adobe Acrobat files.
  • Hyperlinked documents, such as documents formatted for Web browser viewing with embedded links among documentation components.
  • On-line documentation stored on a vendor Web site that can be viewed with a Web browser or downloaded and stored on a local computer system
  • Embedded documentation, such as manuals, tutorials, and multimedia presentations included on a CD and installed as an integral part of an application.
  • Electronic system models, such as text and graphics formatted and stored in graphics file formats such as GIF, JPEG and Visio
  • Tool-specific systems models such as those developed with integrated programming environmrnts, DBMSs and CASE tools.

The focus will now be on the preparation of user documentation and on some of the techniques that could be used to design a more effective and useful user documentation. Although the text briefly covers some of this material, you should consult the specialized literature if you are serious about developing quality user documentation.

2. User Documentation:

2.1 User's Manual:

• Construction can follow two different patterns:
  1. Organise your information in a similar structure to your program. Hence, navigating through your help is similar to navigating through the program. Obviously, extra links may take you from one place in your help to another which cannot be done in the program.
  2. Specify all of the activities that the user is required to do and provide instructions for completing each activity. Your Table of Contents will be the names of the activities. There may be some (considerable even) duplication of some tasks to be performed across different activities.
• Should contain
  • clear headings
  • screen images with arrows etc. highlighting the appropriate part
  • number the steps involved to complete a task
    - similar to a recipe

2.2 Online Help

• construction similar to User's Manual
• index and table of contents can be automatically generated
• can include hyperlinks

2.3 Online Computer-Based Training package

• similar to video
• expensive and time-consuming to produce
• good for training many users that cannot be contacted directly
• may include video to enhance description

3. Writing User Documentation

Why is it important? Inadequate user documentation causes at least five specific problems:

1. Human errors
2. Rejection of systems or programs
3. Wasted time and equipment
4. Increased training costs
5. Possible legal proceedings (http://www.badsoftware.com/baddocs.htm)

Several key questions need to be addressed before preparing any user documentation

• what is it's purpose?
• what is the appropriate media?  (paper, on-line, video etc)
• who are the intended audience? what is their experience?
• what is an appropriate style for the intended audience?
• who should write the documentation?
• if an external writer is contracted should they be involved  in the systems development process?

• to teach a user how to use an application
• to provide help for skilled users
• to teach a user how to install and maintain an application
• to provide technical support for users
• to guide users through system operation
• or all of the above

2.  When selecting an appropriate media, you may consider the following

• on-line documentation for tutorial material?
• advantages:  a user doesn't have to shift attention between the application and the instructional material, it allows the user to practice the skills needed to use the system, it allows users to work at their own pace
• break up written documentation into several components based on task?
• For example, this may involve the use of reference cards that are based on task or on a problem type

There could be five basic audience types

• Parrot  [only capable of following step by step instructions, has little or no understanding of the system ]
• Novice [ has an understanding of what the system is supposed to do, but cannot use the system]
• Intermediate [ is able to partially use the system, but needs guidance]
• Expert [ is able to use the system and only needs help with complex tasks or rare tasks]
• Casual [ not really a user, but someone who may use the system infrequently, they could be considered as an expert user of another system]

most users fall into a category from novice through to expert.

Reading behaviours will vary according to the audience

possible reading behaviours are:

*searching - meanings of particular terms
*scanning - reading quickly, finding specific terms
*skimming - reading for the general drift

The problem you have is that novice users become experts and that your documentation has to cater for more than one audience type. The identification of intended audience(s) is important. This will determine the style of the documentation.

There are several alternatives to an 'essay' style, when preparing user documentation. These include

• text flowchart
• matrix, table or tree diagram
• text picture/'comic book'
• play script
• structured writing
• STOP method

Obviously some systems will lend themselves to a particular style more than others

Text Flowchart

• A flowchart, annotated by text.
• The style is useful  for both novices and experts. It is also useful for tackling about step by step procedures.
• The text gives the detail, the flowchart gives a visual overview and a  link is established between the two
  by labelling.

Matrix, Table or Tree Diagram (examples)

• A good way of establishing cause and effect. May have limited use in an IS context

Text Picture/ Comic Book (example)

• mainly graphics supported by limited text
• This approach is good for:
  •  avoiding jargon
  •  overcoming language barriers
  •  improves clarity (where text may be misread)
  •  and can draw on user experience beyond the computing domain.
• However because it is graphically based it is expensive to produce and may not function well in a dynamic software environment.
• It is more suited to a static situation.

Play script (example)

• 'Who does what & when'
• Good for co-ordinating the activities of several people
• However if you use this approach remember to use action words, the present tense, short sentences and express things in 'plain english' . You should always  link actions together.
• An example taken from a piece of documentation that describes the procedures to followed when collecting time cards in a payroll system

Structured Writing

• This technique can be used under most circumstances.
• Outline may be similar to the organisation of this lecture document
• Hints:
  • You should break the information into visible blocks that could be outlined
  • divide the page into 2 columns:
    1. label in left hand column
    2. content in right hand column
  • use standard labels to define each block
  • use bulleted lists to avoid burying information
  • read vertically/avoid horizontal diagrams
  • each block is independent/ but may be related in  sequence
• General Guidelines:
  

  Component Writing Rule Overview A glossary of structured writing terms and two format rules of the structured writing style are presented on this page: the concept of blocks and the use of labels.   Glossary of structured writing terms A page is called a map. A paragraph or closely allied group of paragraphs is called a block. A sentence is called a chunk. A heading is called a label.   Concept of blocks Present information in visible blocks that are outlined. This makes information bite-sized and localizes all the information on one topic or aspect of that topic in one physical place.   Use of labels Standardize labels and their locations on the page. Side labels are restricted to the left column and do not cross over into the text column on the right. This type of label allows the reader to read the text uninterruptedly, whereas conventional cross-headings interrupt the text and strongly imply borders. Therefore, use side labels rather than cross labels. Structured writing's use of such left-hand column labels coincides with the research that suggests that "the left half of the page has a strong influence on reader attention". You can speed retrieval of informa­tion and improve readability by using such side labels .

Stop Method

• Divide page into two columns
  1. left contains text
  2. right contains screen image
• text explains details of the screen
• This technique could be used when a concept can be expressed by both diagram and text
• Remember that the left side of the brain works with linear & sequential logic (i.e. text) whereas the right side deals with spatial & visual concepts (i.e. graphics)

References:

• Shelly, Cashman & Rosenblatt, Systems Analysis and Design, 6th Edition,  Course Technology, 2006.

NOTE: this webpage has not been brought up to WCAG 1.0 standard nor does it contain validated HTML