11.1

Lecture 11

Communication and documentation during systems development

IMS2805 - Systems Design and Implementation

11.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.

11.3

Communication and documentation

Information systems documentation: System specifications: e.g. requirements,

design, software; data dictionary/ repository, manuals, etc.

Written reports PresentationsSee additional notes on the unit web pageincluded with the lecture notes for week 8

11.4

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.

What is documentation?

11.5

Information Systems Documentation

User Manual Systems Manual Data Manual Program Specification Manual Operations Manual

11.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.

11.7

Systems manual

Purpose: to enable technical staff to understand the system so that

they can: modify the system evaluate the system’s behaviour fix errors in the system

Contents: overview of the system descriptions of all components system specifications controls, errors, audit trails.

11.8

Contents:• Files - schemas, sub-schemas, file

layouts.• Inputs/Outputs - reports; inputs• Data Elements• Data Analysis - logical and physical

data model

enables (technically-oriented) developers and maintainers to:

understand what data is used and where. identify the effects of changes relating to data.

Data Manual

11.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

11.10

Operations manualPurpose: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.11

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

Planning large-scale system operations:Large scale systems require:

• breakdown of the work into jobs (individual programs)

• scheduling of these jobs into a sequence

Operations Manual

11.12

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)

Good Documentation

11.13

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

Planning your documentation

11.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

11.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

11.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

11.17

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

Choose appropriate media

11.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

11.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

11.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

11.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

11.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.

11.23

Specify the document

Draft and edit the document

Review the document

Publish the document

Maintain the document

Not OK

OK

The Documentation Process

11.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 you’re looking for?

11.25

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

Good Documentation

11.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.

11.27

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

Good Documentation

11.28

Users’ level of familiarity with the system Novice

Understands isolated concepts ... able to follow commands and functions in isolation;

IntermediateExperienced novice users ... able to see the context for certain command choices and functions;

ExpertDeals with problems globally ... makes use of all the available functions ... requires only brief reminder help

CasualUses 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

11.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.

11.30

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.

Audience learning styles

11.31

Support reading styles Critical reading

Reading for evaluation purposes

Receptive readingReading for thorough comprehension

use examples and metaphors use interrelated examples

SearchingLooking through with attention to the meaning of specific items

supply a range of reference aids structure the document clearly

11.32

Support reading styles

Scanning Reading quickly with the purpose of finding specific items

supply a range of reference aids use graphics

SkimmingReading for the general drift of the text

use clear layout use topic sentences in paragraphs

11.33

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 ?

Orientation of the document

11.34

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

numbering

11.35

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.

Document format

11.36

Information is often inaccessibleUse:

Glossaries Indexes (very important) Contents page Others

Numbering systems Page, Sections, paragraphs, items Section dividers - tabbed card, coloured pages, Section/chapter summaries

Reference aids

11.37

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

Types of visual aids

11.38

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

Effective graphics

11.39

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.

Layout and pagination

11.40

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

typography

11.41

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

Colour

11.42

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

Quick Reference Guide

11.43

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.

On-line documentation