Introduction to Business Systems Development

1
Introduction to Business Systems Development
2
Topic 10
Documentation
Satzinger 4th edn. Chapter 8,15
3
System Documentation

• System Documentation is a permanent form of
  communication between owners, analysts, builders
  and users of the system

4
What is system documentation?

• All written records related to the project
  development
• manuals, charts, forms etc (the deliverables)
• All user documentation
• training guides, tutorials, on-line help,
  policies, procedures etc
• Operation and production
• instruction schedules, data, messages, internal
  code comments etc

5
Documentation

• Not restricted to the printed page
• Online help systems
• Online user manual
• Multimedia -Video, CD, DVD or audio tape

6
Why is documentation required?

• Minimises confusion
• Measures progress
• Provide essential support for the system
• Aids in the ongoing operation and maintenance of
  the system
• Enables the system to be kept effective for the
  long term
• Serves as a safety net
• Self-preservation

7
Good documentation has a...

• Purpose
• - sales tool, reference guide etc
• - acts as communication between people
• Subject
• - description of what the system is
• - what it does and how it does it
• Audience
• - owners, designers, builders, users
• - those who provide support and revise the
  system

8
Documentation can be a separate thing, a body of
information that describes the system ORSystem
s documentation can be an integral part of the
system development process

• A system and it's documentation
  should be part of the same
  project

9

• The documentation needs to be developed with the
  system
• This is the developer's responsibility
• The documentation needs to be updated with the
  system
• This is the user / owner responsibility

10
Documentation

• Automated documentation is the norm
• Electronic manuals
• Hyperlinked documents
• On-line documentation
• Embedded documentation
• Electronic system models
• Tool-specific system models

11
System Documentation

• Descriptions of system functions, architecture,
  and construction details, as used by maintenance
  personnel and future developers
• Generated as a byproduct of development
• Includes source code
• Includes analysis and design models

12
System Documentation Generated During Development
Satzinger et al. (2006) Figure 15-23
13
User Documentation

• Descriptions of how to interact with and maintain
  the system, as used by end users and system
  operators
• Topics include
• Startup and shutdown
• Keystrokes, mouse, or command functions to
  perform specific functions
• Specific program functions
• Common errors and corrections

14
What types of documents are required for a system?

• Training Manuals
• User Manual
• Operator Manual
• Systems Manual
• Program Specifications
• Data Manuals
• Others, as appropriate
• Installation manuals

15
Documentation for Users

• Training Manual
• to allow new users to learn to use the system
• should match the training program
• Possible styles
• - Step by step self teaching
• - 'Classroom' instruction

16
Training and User Support

• Without training, user error rates will be high
• Training considerations
• Frequency and duration of use
• Need to understand systems business context
• Existing computer skills
• Number of users
• Training and support is ongoing

17

• User Manual/Procedure Manual Instructs the user
  on how to Operate hardware Execute
  program/s Use the software Correct
  mistakes Solve problems Note There may be
  several manuals for users. Each may cover the
  material necessary for a particular user or
  category of user

18
Technical Documentation

• Technical operations manual
• Installation manuals
• System and program documentation

19
Operators ManualInstructs operations staff on
the use of the system.

• who to contact
• for Development support
• for System support
• for Technical support
• for User support

• Contents
• files used
• schedules
• possible errors
• peripherals used
• form requirements
• run time
• backup/recovery/restart

20
Systems Manual

• Provide a quick understanding of the system
• To understand if the system is operating as
  designed
• To give the necessary view so that modifications
  can be made
• Contents
• Overview
• System specifications
• Sub-system descriptions

21
Data Manual

• Provides an understanding of data used by the
  system
• Demonstrates data structure so that effects of
  charges in data can be seen
• Contents
• Files
• Inputs/Outputs
• Data Elements
• Data Structures
• Data Analysis
• (Logical and physical data models)

• Permissions
• Entity life histories
• Validation/controls

22
Program Specification Manual

• Main source of communication between analysts and
  programmers
• Document of what the program does
• for maintenance purposes
• Contents
• Screen/report designs
• Structure Chart
• Design Specifications
• Listings
• Test data Test plans

23
Documentation Design Issues

• Controls - Security/access/consistency
• Sensitive information?
• (ie. how to get around passwords or not letting
  all users see entire system)
• Procedures for changing documentation.
• who is allowed to change manuals
• who is responsible for assuring updates in manuals

24

• Planning for Updates - always plan for updates,
  consider
• Binding frequency of updates
• size of document
• number of documents.
• Paging use of sections
• allow easy replacement of significant portions
  of a document
• page numbers are difficult to alter
• consider other numbering techniques.
• Conveying the message - use tables, trees,
  matrix, diagrams, flow charts, pictures or
  whatever else is necessary

25

• Media type
• limitations on screens are different than for a
  written manual
• density of information must be much lower
• easier to flip through pages than screens

26
Design of On-Line Documentation

• Each screen must be stand-alone
• do not rely on any prior knowledge of the readers
• Layers of information can be nested
• Keep each individual screen brief
• Graphics and layout are very important
• dealing with such a limited amount of space
• Individual words take on added significance
• In moderation, colour, blinking or inverse video
  can be used

27

• The help information should be presented in a
  "window" to alleviate the change from
  problem-solving to learning mode
• The reader should not be confronted with a solid
  block of text
• On-line documentation should be sensitive to the
  context the user was in
• On-line documentation must be consistent (in
  style and content) with any accompanying paper
  documentation
• Structured writing format is ideal for on-line
  documentation

28
Document Design Techniques

• Must convey information to the reader in a manner
  which matches the needs of the reader
• Documents are used as references and are rarely
  read from beginning to end

29
Techniques (to think about)

• A brief statement about what the manual is meant
  to achieve and who it is written for
• can help users quickly identify the manual they
  used
• A table of contents
• Straight columns can be difficult to use
• Indentation can be very useful

30
Compare the following
C O N T E N T S Structural Analysis 3 What is
Analysis 4 Problems of Analysis 9 The
User 12 Responsibilities 14 Characteristics 1
5
C O N T E N T S Structured Analysis 3 What is
Analysis 4 Problems of Analysis 9 The
User 12 Responsibilities 14 Characteristics 15
Which is more meaningful and easier to read?
31
Page layouts

• 1. Blocked text
• This is the normal layout for a novel
• Not very useful to a frantic user

Responsibilities Positions in Operations The
responsibilities of a Trainee Programmer are to
1. Learn to code 2. Write simple programs and,
3. Attend training sessions. A Programmers
responsibilities are to 1. Improve code skills
and 2. Learn Job control language
32
Page layouts
2. Playscript A two column format with
performers/actors in one column and actions in
the other
Responsibilities Positions in
Operations Trainee Programmer 1. Learn to
code 2. Write simple programs 3. Attend
training sessions Programmer 1. Improve code
skills 2. Learn Job control language Actor Act
ion
33
Structured Writing

• Label Brief Description
• Editing Editing requires the use of special keys.
  The four arrow keys, the delete key and the
  delete back key are very useful.
• Saving Saving means to place the relevant data
  on a file so that it can be used later.
  Changes are not saved permanently until the
  computer is instructed to save the information.
• Deleting Deletion means to permanently remove
  data from the system.

34
Structured Writing (continued)

• Blocks should be short
• Labels assist in identifying needed text
• Use lines to visibly break the blocs
• Each page should deal with a single concept

35
Formats

• Bullet lists
• Use numbers only if necessary for identification
• Numbers can be difficult to update
• Be careful not to let list dominate the page

36

• Paragraph identification
• 3.0
• 3.1
• 3.1.1
• 3.1.2
• 3.1.2.1
• 3.1.2.2
• 3.2

Title Subtitle Topic Note Topic Topic S
ubtitle Subtitle
Can be useful for identification. Numbers can be
confusing Use only if necessary
Different styles of lettering combined with
keyword allows quick identification of
subordination Easy to understand.
37
Summary

• System Documentation
• What is it?
• What makes it good?
• What types of documentation are required?
• What are some of the design issues?
• Design of on-line documentation

38
Homework

• Review this lecture
• Read and summarize Satzinger et al. pages
  587-588 pgs 602-611
• Complete
• Review Questions
• 14 - 17page 613
• Thinking Critically 5 6 p. 613
• Assignment 2
• Exam preparation the next session is your last
  class opportunity to prepare for the exam