View
231
Download
6
Tags:
Embed Size (px)
Citation preview
1
IMS9001 - Systems Analysis and Design
Communication and documentation during systems development
11.2
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 11
11.3
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.4
Information Systems Documentation
User Manual Systems Manual Data Manual Program Specification Manual Operations Manual
11.5
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.6
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.7
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.8
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.9
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.10
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.11
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.12
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.13
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.14
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.15
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.16
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.17
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.18
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.19
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.20
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.21
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.22
Specify the document
Draft and edit the document
Review the document
Publish the document
Maintain the document
Not OK
OK
The Documentation Process
11.23
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.24
Definitions of Quality
Degree of excellence (Oxford) Fitness for purpose (AS1057)
includes quality of design, the degree of conformance to design, and it may include such factors as economic or perceived values
Ability to satisfy stated/implied needs (ISO8402)
Conformance to requirements (Crosby, Horch)
11.25
Determining Quality ..
when having a meal in a restaurant when purchasing a car when buying a computer
The requirements vary immensely, and some of the success measures are very hard to quantify...
Quality means different things to different people .. and it varies in different situations
11.26
Information systems: quality issuesThe system: does not meet the client’s business or processing
needs does not support the client’s working methods is unstable and unreliable does not improve productivity is difficult to use or requires excessive training to
use is expensive to maintain
11.27
The system: is incomplete is expensive to operate has a short life span is delivered late costs more than budget cannot grow with the organisation does not produce a return on investment
Information systems: quality issues
11.28
“Effort spent on software maintenance is greater than that spent on software development.”
“An error is typically 100 times more expensive to correct in the maintenance phase on large projects, than in the requirements phase.”
Boehm, B. (1981) Software Engineering Economics
Error detection in systems
11.29
Error Detection
* The cost of detecting and correcting errors rises greatly during
the systems development cycle.
In addition to this is the cost to the organisation of having an incorrect system
Initiation Analysis Design Implementation
$
11.30
Quality Costs
Review,Inspection,
Re-do,
User complaints, Downtime,Loss of sales, Re-testing,
Re-documenting, Re-training,Overtime, Customer complaints,
Financial losses, Employee turnover
The tip of the Iceberg
The hidden costsof not having quality
systems
Obvious upfront coststo the organisation
11.31
Quality dimensions
Correctness - Does it accurately do what is intended?
Reliability - Does it do it right every time?
Efficiency- Does it run as well as it could?
Integrity - Is it precise and unambiguous?
Usability - Is it easy to use?
11.32
Quality dimensions
Maintainability - Is it easy to fix? Testability - Is correctness easy to check
and verify? Flexibility - Is it easy to adapt and
extend? Portability - Can it be easily converted? Reusability - Does it consist of general
purpose modules? Interoperability - Will it integrate easily with
other systems?
11.33
The Quality Process
The quality process involves the functions of: Quality control - monitoring a process and
eliminating causes of unsatisfactory performance
Quality assurance - planning and controlling functions required to ensure a quality product or process
11.34
Implementing a Quality System
Quality must start at the top - Executive sponsorship is vital.
Everyone must be involved and motivated to realise that they have a responsibility towards the final product, its use, and its quality.
Improve job processes by using standards, and preparing better documentation (using project control methodologies).
Use a Quality Assurance group. Use technical reviews.
11.35
Standards
Levels of standards Industry / National / International Organisational
Industry Capability Maturity Model (Humphrey 1989)
See Whittten et al (2001) pp 76-77 National / International
Standards Australia (AS 3563) International Standards Organisation (ISO 9000)
Organisational The organisation may adopt or tailor industry, national or
international standards.
11.36
Standards
Standards can be of varying levels of enforcement and types which will depend on the organisation and project variables. For example : mandatory practice: must be adhered to advisable practice: can be breached with
good reason in the form of a checklist, template, or form.
11.37
Standards - Examples
• Document template (form, e.g. template for these slides)• Acceptance test sign off form (form)• Screen standards (standard - mandatory practice)• Unit test process (standard - mandatory practice)• COBOL II standards (standard - mandatory practice)• Post implementation review procedure (advisory practice)
Note: different organisations and projects will have different views about whether a standard is mandatory or advisable.
11.38
Quality reviews
Reviews are used in the quality control and quality assurance functions. There are two main forms of review:
Quality Assurance: management reviews
Quality Control technical reviews
11.39
Management or Project Review
Management must check the baseline for a deliverable to see that it meets the quality assurance requirements.
This may involve simply noting that a technical review has passed a particular deliverable. The manager can then be assured of quality(given that the manager has actively taken part in the development of the quality system)
The manager can then alter the project plan if necessary to allow for delays or early completion.
11.40
Technical Reviews
A technical review is a structured meeting where a piece of work, which has previously been distributed to participants, is checked for errors, omissions, and conformance to standards.
All deliverables need review, otherwise how do you control quality?
The review is part of quality control and must produce a report so that the quality assurance function can be satisfied.
The report may be a checklist which indicates that the deliverable passes/fails the quality requirements for that type of deliverable.
This report is part of the baseline for the deliverable.
11.41
Technical Reviews
A technical review: is a formal meeting of a project team which is guided by an
agenda and standards allows input from many people produces a report which is made public requires committed participants to be responsible and
accountable for their work is educational as it clarifies standards, and highlights
strengths and weaknesses of the team’s skills and knowledge
expects all participants to be responsible for the resulting quality of the artefact
11.42
Technical Review Roles
review member Know the review process Be positive and supportive Interested in improving the quality of the deliverable and the
review process review leader
Secure agreement on objectives and standards Encourage input from all participants, and politely silence overly
talkative participants Facilitate agreement to ensure action on the deliverable
scribe Record all issues clearly, accurately, and unambiguously.
If not sure of a particular issue, seek clarification
11.43
Quality in Systems Development(must be embedded in the process)
Initiation
Analysis
Design
Implementation
Review
MaintenanceQuality
Documentation
Ethics
ProjectManagement
Analysts Role
11.44
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 (2005) Modern
Systems Analysis and Design, (4th edition), Pearson Education Inc., Upper Saddle River, New Jersey, USA. Appendix 1
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.45
References (2)
Abel, D.E. and Rout, T.P. (1993) Defining and Specifying the Quality Attributes of Software Products The Australian Computer Journal 25:3 pp 105 - 112 (particularly pp 105 - 108)
Dahlbom, B. and Mathiassen, L.(1993). Computers in Context: The Philosophy and Practice of Systems Design. Cambridge, Mass.: NCC Blackwell. (particularly pp 135 - 157)
Elliot, S. (1993) Management of Quality in Computing Systems Education, Journal of Systems Management, September 1993 pp 6-11, 41-42 (particularly pp 6-8)
11.46
References (3)
Perry, W.E. (1992) Quality Concerns in Software Development. The Challenge is Consistency. Information Systems Journal 9:2 pp 48 - 52
Standards Association of Australia (1991). Australian Standard 3563.1 -1991: Software Quality Management System. Part 1 Requirements
Standards Association of Australia (1991). Australian Standard 3563.2 -1991: Software Quality Management System. Part 2 Implementation Guide