Communication and documentation during systems development

1
IMS2805 - Systems Design and Implementation

• Lecture 11
• Communication and documentation during systems
  development

2
References

• WHITTEN, J.L., BENTLEY, L.D. and DITTMAN, K.C.
  (2001) 5th ed., Systems Analysis and Design
  Methods, Irwin/McGraw-HilI, New York, NY.,
  Chapters 5, 8
• HOFFER, J.A., GEORGE, J.F. and VALACICH (2002)
  3rd ed., Modern Systems Analysis and Design,
  Prentice-Hall, New Jersey, Chap 17
• ANDERSON, P.V. (1995). Technical writing A
  reader-centred approach, 3rd ed. Harcourt, Brace
  Co., Fort Worth.
• BROCKMAN, J. R. (1990). Writing better computer
  user documentation - From paper to hypertext.
  John Wiley and Sons, Inc., New York.

3
Communication and documentation

• Information systems documentation
• System specifications e.g. requirements, design,
  software data dictionary/ repository, manuals,
  etc.
• Written reports
• Presentations
• See additional notes on the unit web page
• included with the lecture notes for week 8

4
What is documentation?

• Not necessarily a piece of paper.
• Any permanent medium used to communicate to other
  people can be classed as documentation
• Product and documentation should be developed at
  the same time
• DOCUMENTATION IS PART OF THE PRODUCT
• Documentation is communication
• the objective is to
• create a specific effect
• on particular readers
• who want specific information,
• have particular characteristics and
• will read under particular circumstances.

5
Information Systems Documentation

• User Manual
• Systems Manual
• Data Manual
• Program Specification Manual
• Operations Manual

6
User manual

• Purpose
• a contractual obligation
• a marketing tool
• a training tool
• a reference for non-technical people
• a memory in case key staff leave
• Contents
• what the system is about (narrative)
• how to use the hardware how to carry out tasks -
  details of manual procedures involved how to
  enter data, produce output, interpret output
• how to correct mistakes
• how to solve typical problems
• how to ensure security
• how to perform backup and recovery.

7
Systems manual

• Purpose
• to enable technical staff to understand the
  system so that they can
• modify the system
• evaluate the systems behaviour
• fix errors in the system
• Contents
• overview of the system
• descriptions of all components
• system specifications
• controls, errors, audit trails.

8
Data Manual

• enables (technically-oriented) developers and
  maintainers to
• understand what data is used and where.
• identify the effects of changes relating to data.

• Contents
• Files - schemas, sub-schemas, file layouts.
• Inputs/Outputs - reports inputs
• Data Elements
• Data Analysis - logical and physical data model

9
Program specification manual

• Purpose
• to support communication between analyst/designer
  and programmer
• to describe in detail what the program does
• for initial development
• for maintenance.
• Contents
• design specification (narrative describing the
  purpose and general functions of the program),
• listing of each program (for maintenance
  purposes),
• layouts of files or database area used,
• layouts of screens and reports,
• test plan, test data, test conditions, test
  results

10
Operations manual

• Purpose
• Large scale systems may need operations support.
  If so, a separate operations manual is needed to
  instruct operations staff in operating and
  controlling the new system.
• Contents
• system overview (purpose/functions of the system)
• processing flow
• system start-up/shut-down
• restart and recovery procedures
• security/backup procedures
• tape/disk library instructions
• user contacts and procedures
• priority of jobs
• report distribution information

11
Operations Manual

• Planning large-scale system operations
• Large scale systems require
• breakdown of the work into jobs (individual
  programs)
• scheduling of these jobs into a sequence

• For each job
• narrative description of the job
• job flowchart
• job schedule requirements
• job set up instructions
• input control procedures
• operator's instructions
• job rerun/recovery procedures
• data control instructions
• report distribution instructions

12
Good Documentation

• For a user, the system is only as good as the
  documentation describing it
• Good documentation
• reduces the need to refer problems to system
  developers
• overcomes users fears of equipment and software
• ensures successful first encounters with a system
• enables users to find what they want and
  understand it when they find it
• is accurate and complete
• is written for the intended audience and purpose
• has good reference aids (table of contents,
  thorough index, cross-referencing)

13
Planning your documentation

• Audience - sets the tone, style, language and
  emphasis
• level of computer sophistication
• background, training, or education
• attitude towards your message
• cultural background
• Purpose - why is the documentation necessary?
• identifies the content
• indicates the level of detail required
• Medium
• paper-based manuals and reference cards
• on-line documentation
• aural and visual training materials

14
Audience

• Type of documentation Audience
• User Manual users - new, intermediate,
  experienced
• System Manual client, maintenance team
• Data Manual (Data Dictionary) developers,
  maintenance team
• Program Manual developers, maintenance
  team
• Operations Manual operators, technical staff

15
Document organisation

• Principles
• Make the organisation of material apparent to
  readers
• Tell them what you are going to tell them before
  you tell them
• Organise the document in ways expected by
  readers
• chronological order
• most important to least important
• order of need
• order of difficulty
• question / answer order
• compare/ contrast order
• alphabetical order

16
Documentation organisation

• Chunking - the rule of seven
• Labelling - briefly describe upcoming information
• Relevance - put related information together
• Consistency
• Hierarchy of chunking and labelling - Chapters,
  Sections, Topics
• Integrated graphics
• Accessible detail - access routes to different
  levels of detail

17
Choose appropriate media

• Manuals
• Most common ... not good for trivial problems.
• Brochures
• Main capabilities are highlighted ... emphasises
  simplicity and elegance, not the detail of
  manuals. 4 - 8 pages fully describing the
  system.
• Quick reference guides
• 90 of the time 90 of the needs of 90 of the
  readers can be met by a simple summary card.
• On-line help
• Ideal reminders ... useful as an aid for
  experienced user BUT are not a replacement for
  manuals

18
Online vs paper-based documentation

• Online easier to distribute and maintain
• Printing costs reduced
• Online enables different search paths to the same
  information
• Easier for user to become disoriented
• Online documentation must be written differently
• Online documentation must be consistent with
  paper-based documentation

19
Reference Aids

• Information is often inaccessible
• Use
• Glossaries
• Indexes (very important)
• Contents page
• Others
• Numbering systems
• Page, Sections, paragraphs, items
• Section dividers - tabbed card, coloured pages,
• Section/chapter summaries

20
Colour and graphics

• Use a minimum number of colours, and be
  consistent and familiar (eg. red for hot) in
  your use of colour codes
• Avoid putting colours from extreme ends of the
  spectrum together .. makes it hard to perceive a
  straight line
• Don't rely on colour alone to discriminate
  between items
• Graphics can make a document more effective
• points in a text can be emphasised
• can increase reader's interest
• can replace, clarify or simplify the text

21
Layout and Pagination

• Layout
• Be consistent in your layout
• Use type size (at least 4 points different) or
  bolding to indicate relative importance or weight
• Page
• Use a page size suited to the environment that
  the document is going to be used in
• Make sure page numbering is clear

22
Planning a Cost-time Schedule

• Why? - Often documentation is forgotten, ignored
  or dismissed as not being important.
• Aim - to develop an estimate of the time required
  for documentation DURING development .. not a
  trivial task.
• Time vs Cost - be realistic about your estimates
  ..
• Time saved in the documentation task will be
  wasted many times over explaining things not
  included or not clearly described in the
  documentation provided.

23
The Documentation Process
Specify the document
Draft and edit the document
Not OK
Review the document
OK
Maintain the document
Publish the document
24
Effective documentation check list

• Objective clearly stated
• Target audience identified
• Consistent approach used (wording, structure,
  layout) - templates help
• The principles of documentation organisation and
  development have been followed
• Maintenance process in place
• Put yourself in the users position - can you
  easily find what youre looking for?

25
Good Documentation

• can improve a product's reputation - for a user,
  the system is only as good as the documentation
  describing it.
• reduces the need to refer problems to system
  developers
• overcomes users fears of equipment and software
• ensures successful first encounters with a system
  which lead to greater acceptance and use of the
  system
• enables users to find what they want and
  understand it when they find it
• is accurate and complete
• grows with the readers

26
Good Documentation

• is written for the intended audience and purpose
• has a consistent layout that clarifies the
  structure of the document
• uses an appropriate layout for the type of
  material
• highlights important points
• avoids jargon, or where jargon is necessary gives
  definitions or explanations
• uses clear examples that are easy to visualise
• is neither wordy and verbose nor too brief and
  concise
• has good reference aids (table of contents,
  thorough index, cross-referencing)
• is easy to update
• is produced in an easy-to-manage physical format.

27
Good Documentation

• allows easy access to the appropriate level of
  detail
• has more than one navigational path
• provides easy access to additional relevant
  information
• decreases reading time, error rates, application
  support
• increases use of application functionality
• improves efficiency, as people understand the
  system they are working with
• increases user satisfaction

28
Users level of familiarity with the system

• Novice
• Understands isolated concepts ... able to follow
  commands and functions in isolation
• Intermediate
• Experienced novice users ... able to see the
  context for certain command choices and
  functions
• Expert
• Deals with problems globally ... makes use of
  all the available functions ... requires only
  brief reminder help
• Casual
• Uses the system on rare occasions ... familiar
  with the system but forgets details .. does not
  like to be overloaded with information.
• Documentation should cater for users moving
  quickly from one level to the next

29
How do adults learn?

• Effective documentation presents materials in
  ways appropriate to the actual ways adults learn.
• Adults
• are impatient learners
• want to do something productive quickly
• skip around manuals and on-line documentation and
  rarely read them fully
• make mistakes but learn best from them
• are motivated by self-initiated exploring
• are discouraged by large manuals with each task
  decomposed into sub-tasks to the nth degree.

30
Audience learning styles

• Aural learners
• like someone to tell them what to do
• prefer audio visual media, training courses with
  trainer, telephone support, expert users.
• Visual learners
• want to have a clear picture of what the software
  product is, what it can do, and how it is used
  before doing anything with it
• prefer paper media .. manuals, brochures,
  references guides, etc..
• Experimental learners
• like to learn by doing
• prefer on-line tutorials and help that they can
  call up when they need it.

31
Support reading styles

• Critical reading
• Reading for evaluation purposes
• Receptive reading
• Reading for thorough comprehension
• use examples and metaphors
• use interrelated examples
• Searching
• Looking through with attention to the meaning of
  specific items
• supply a range of reference aids
• structure the document clearly

32
Support reading styles

• Scanning
• Reading quickly with the purpose of finding
  specific items
• supply a range of reference aids
• use graphics
• Skimming
• Reading for the general drift of the text
• use clear layout
• use topic sentences in paragraphs

33
Orientation of the document
based on the structure and facilities of the
software .. (implementation orientation)
according to anticipated users of the system
(user-role orientation) based on an
analysis of how the user would use the
system(task oriented)

• to learn and find your way around the system
  requires you to already know it !!!!!
• roles not easy to define, jobs and titles change
  frequently, a lot of duplication in the
  documentation.
• who performs the task ?what action begins each
  task ?what are the steps in the task ?what
  actions end each task ?any conditions alter the
  task ?

34
numbering

• numbered lists use numbers only if order is
  important avoid roman numerals
• slower to read,
• people make mistakes with them
• bulleted lists use for lists of items in no
  particular order
• section numbering only use if there is a reason.
• underlining use for keywords ... do not overuse

35
Document format

• Alternatives to essay writing
• Text flowchart
• Matrix, table or tree diagram
• Text picture
• Playscript
• Structured writing
• STOP method
• No one documentation format will satisfy all
  situations.
• Be prepared to modify or combine formats to suit
  the audience and the task.

36
Reference aids

• Information is often inaccessible
• Use
• Glossaries
• Indexes (very important)
• Contents page
• Others
• Numbering systems
• Page, Sections, paragraphs, items
• Section dividers - tabbed card, coloured pages,
• Section/chapter summaries

37
Types of visual aids

• Displaying data
• tables
• bar graphs
• pictographs
• line graphs
• pie charts
• Showing how something looks or is constructed
• photographs
• drawings

• Showing how to do something
• photographs and drawings
• Explaining a process
• flowcharts
• diagrams
• Displaying management info
• organisation charts
• schedule charts
• budget statements

38
Effective graphics

• Graphics can make a document more effective
• points in a text can be emphasised
• can increase reader's interest
• can replace, clarify or simplify the text
• increases the skim and scan ability of a document

39
Layout and pagination

• Layout
• Pull the readers eye to the areas of the page you
  wish by using contrasting typographic elements
  because the reader's eye naturally moves across
  the page or screen following the Gutenberg
  diagram

Point of eye's arrival on page
Point of eye's exit on page

• Be consistent in your layout ... the user
  develops a model that, if consistent, helps them
  to guess what will come next
• Use type size (at least 4 points different) or
  bolding to indicate relative importance or
  weight.
• Page
• Use a page size suited to the environment that
  the document is going to be used in
• Smaller sizes can be more difficult to photocopy
  and pirate.

40
typography

• Typeface does the typeface look OK?
• use serified type for extended reading
• minimise the number of typefaces used in a
  document
• Posture keep it straight for extended reading
  use italics (rarely) for contrast
• Type size use a minimum of 10 or 12 point
• Composition use a mixture of upper and lower case
  ... easier to read
• Appointment use ragged right appointment ...
  easier to read
• Word spacing use less space between words than
  between lines
• Letter spacing use proportional spacing - space
  devoted to a letter proportional to its width ...
  easier to read words that are chunked together

41
Colour

• Bulk of research reveals that colour undermines
  comprehension
• Cautions
• Older people need brighter colours to see them
  ...younger people find them distracting
• A line of coloured text is viewed using a
  "sweeping" mode rather than a linear mode ...
  colours appreciated rather than content
  comprehended
• The interactions of different colours can cause
  optical illusions
• Effective use
• Use a minimum number of colours, and be
  consistent and familiar (eg. red for hot) in
  your use of colour codes
• Avoid putting colours from extreme ends of the
  spectrum together .. makes it hard to perceive a
  straight line
• Don't rely on colour alone to discriminate
  between items

42
Quick Reference Guide

• contains only relevant information
• selective in coverage, addresses its audience
• has adequate white space (active rather than
  passive)
• uses a legible type size - usually 10 or 12
  point
• has effective headings that
• logically group the information
• are easily decipherable by contrasting page
  placement, typeface, boldness or size.
• fits the environment
• size, paper-type, binding and placement suits
  on-the-job use
• can readers use their hands to turn pages or to
  hold the card? use a wall poster instead?
• is easily reproducible

43
On-line documentation

• no prior knowledge required - simple to get
  started, each screen must be independent
• layers of information - each individual screen is
  brief, navigation clear, few commands
• use graphics and layout to support the content
• few words - so make each word count - vertical,
  bulleted lists good avoid a solid block of text
  use white space
• careful use of colour, blinking (markers not
  text!) or inverse video can help reader access
• problem-solving and learning modes should be
  separated - use windows or split screens
• should be context sensitive
• must be consistent (style and content) with paper
  documentation.
• must be easy to recover from errors, find the way
  out.