Communication and documentation during systems development - PowerPoint PPT Presentation

Loading...

PPT – Communication and documentation during systems development PowerPoint presentation | free to download - id: 172553-ZDc1Z



Loading


The Adobe Flash plugin is needed to view this content

Get the plugin now

View by Category
About This Presentation
Title:

Communication and documentation during systems development

Description:

Often documentation is forgotten, ignored or dismissed as ... familiar with the system but forgets details .. does not like to be overloaded with information. ... – PowerPoint PPT presentation

Number of Views:23
Avg rating:3.0/5.0
Slides: 44
Provided by: andrewb77
Category:

less

Write a Comment
User Comments (0)
Transcript and Presenter's Notes

Title: 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.
About PowerShow.com