CSE1204 - Information Systems 1 Communication and documentation during systems development

CSE1204 - Information CSE1204 - Information Systems 1Systems 1

Communication and Communication and documentation during documentation during systems developmentsystems development

Monash University, SIMS, Semester One, 2005Monash University, SIMS, Semester One, 2005 22

Communication and documentationCommunication and documentation

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

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

Written reportsWritten reportsPresentationsPresentations

See additional notes on the unit web pageSee additional notes on the unit web page

included with the lecture notes for week 8included with the lecture notes for week 8


Not necessarily a piece of paper.Not necessarily a piece of paper.Any permanent medium used to communicate Any permanent medium used to communicate to other people can be classed as to other people can be classed as documentationdocumentationProduct and documentation should be Product and documentation should be developed developed at the same timeat the same time

What is documentation?What is documentation?


Documentation is Documentation is communicationcommunication

the objective is to:the objective is to:create a create a specific effectspecific effect on on particular readersparticular readers who want who want specific informationspecific information, , have have particular characteristics particular characteristics and and will read under will read under particular circumstancesparticular circumstances..


Information Systems Information Systems DocumentationDocumentation

User ManualUser ManualSystems ManualSystems ManualData ManualData ManualProgram Specification ManualProgram Specification ManualOperations ManualOperations Manual


User manualUser manual Purpose:Purpose:

a contractual obligationa contractual obligation a marketing toola marketing tool a training toola training tool a reference for non-technical peoplea reference for non-technical people a a memorymemory in case key staff leave in case key staff leave

Contents:Contents:what the system is about (narrative);what the system is about (narrative);how to use the hardware how to carry out tasks - how to use the hardware how to carry out tasks -

details of manual procedures involved; how to enter details of manual procedures involved; how to enter data, produce output, interpret output;data, produce output, interpret output;

how to correct mistakeshow to correct mistakes how to solve typical problems;how to solve typical problems; how to ensure security;how to ensure security; how to perform backup and recovery.how to perform backup and recovery.


Systems manualSystems manual Purpose:Purpose: to enable technical staff to understand the system so that to enable technical staff to understand the system so that

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

Contents:Contents:overview of the systemoverview of the systemdescriptions of all componentsdescriptions of all componentssystem specifications system specifications controls, errors, audit trails.controls, errors, audit trails.


enables (technically-oriented) developers enables (technically-oriented) developers and maintainers to: and maintainers to:

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

Contents:Contents: Files - schemas, sub-schemas, file layouts.Files - schemas, sub-schemas, file layouts. Inputs/Outputs - reports; inputsInputs/Outputs - reports; inputs Data ElementsData Elements Data Analysis - logical and physical data modelData Analysis - logical and physical data model

Data ManualData Manual


Program specification manualProgram specification manual Purpose:Purpose:

to support communication between analyst/designer and to support communication between analyst/designer and programmer;programmer;

to describe in detail what the program doesto describe in detail what the program doesfor initial development;for initial development;for maintenance.for maintenance.

Contents:Contents:design specification (narrative describing the purpose and design specification (narrative describing the purpose and

general functions of the program),general functions of the program), listing of each program (for maintenance purposes),listing of each program (for maintenance purposes), layouts of files or database area used, layouts of files or database area used, layouts of screens and reports,layouts of screens and reports, test plan, test data, test conditions, test resultstest plan, test data, test conditions, test results


Operations manualOperations manualPurpose:Purpose:Large scale systems may need operations support. If so, a separate Large scale systems may need operations support. If so, a separate operations manual is needed to instruct operations staff in operating and operations manual is needed to instruct operations staff in operating and controlling the new system.controlling the new system.Contents:Contents:

system overview (purpose/functions of the system)system overview (purpose/functions of the system)processing flowprocessing flowsystem start-up/shut-downsystem start-up/shut-downrestart and recovery proceduresrestart and recovery proceduressecurity/backup proceduressecurity/backup procedurestape/disk library instructionstape/disk library instructionsuser contacts and proceduresuser contacts and procedurespriority of jobspriority of jobsreport distribution informationreport distribution information


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

• breakdown of the work into jobs (individual programs)

• scheduling of these jobs into a sequenceFor 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

Operations ManualOperations Manual


Good documentation:Good documentation: reduces the need to refer problems to system reduces the need to refer problems to system

developersdevelopers overcomes users’ fears of equipment and softwareovercomes users’ fears of equipment and software ensures successful first encounters with a systemensures successful first encounters with a system enables users to find what they want and understand enables users to find what they want and understand

it when they find itit when they find it is accurate and completeis accurate and complete is written for the intended audience and purposeis written for the intended audience and purpose has good reference aids (table of contents, thorough has good reference aids (table of contents, thorough

index, cross-referencing)index, cross-referencing)

Good DocumentationGood Documentation


AudienceAudience - sets the - sets the tonetone, , stylestyle, , languagelanguage and and emphasisemphasis level of computer sophisticationlevel of computer sophistication background, training, or educationbackground, training, or education attitude towards your messageattitude towards your message cultural backgroundcultural background

Purpose - Purpose - why is the documentation necessary?why is the documentation necessary? identifies the identifies the contentcontent indicates the indicates the level of detaillevel of detail required required

MediumMedium paper-basedpaper-based manuals and reference cards manuals and reference cards on-lineon-line documentation documentation auralaural and and visualvisual training materials training materials

Planning your documentationPlanning your documentation


AudienceAudience Type of documentationType of documentation AudienceAudience

User ManualUser Manual users - new, intermediate, users - new, intermediate, experienced experienced

System ManualSystem Manual client, maintenance teamclient, maintenance team

Data Manual (Data Dictionary)Data Manual (Data Dictionary) developers, maintenance developers, maintenance teamteam

Program ManualProgram Manual developers, maintenance developers, maintenance teamteam

Operations ManualOperations Manual operators, technical staffoperators, technical staff


Document organisation - principlesDocument organisation - principles Make the organisation of material apparent to Make the organisation of material apparent to

readersreaders Tell them what you are going to tell them Tell them what you are going to tell them

before you tell thembefore you tell them Organise the document in ways expected by Organise the document in ways expected by

readers:readers:chronological orderchronological ordermost important to least importantmost important to least importantorder of needorder of needorder of difficultyorder of difficultyquestion / answer orderquestion / answer ordercompare/ contrast ordercompare/ contrast orderalphabetical orderalphabetical order


Documentation organisationDocumentation organisation Chunking - the rule of seven Chunking - the rule of seven Titles - briefly describe upcoming informationTitles - briefly describe upcoming information Relevance - put related information togetherRelevance - put related information together Consistency – style, voice, emotionConsistency – style, voice, emotion Hierarchy of structure - Chapters, Sections, TopicsHierarchy of structure - Chapters, Sections, Topics Integrated graphics – appropriate, support textIntegrated graphics – appropriate, support text Accessible detail - access routes to different levels Accessible detail - access routes to different levels

of detail (overall/general, specific, fine detail)of detail (overall/general, specific, fine detail)


ManualsManuals Most common ... not good for trivial problems.Most common ... not good for trivial problems.

BrochuresBrochures Main capabilities are highlighted ... emphasises Main capabilities are highlighted ... emphasises

simplicity and elegance, not the detail of manuals. 4 - simplicity and elegance, not the detail of manuals. 4 - 8 pages fully describing the system.8 pages fully describing the system.

Quick reference guidesQuick reference guides 90% of the time 90% of the needs of 90% of the 90% of the time 90% of the needs of 90% of the

readers can be met by a simple summary card.readers can be met by a simple summary card. On-line helpOn-line help

Ideal reminders ... useful as an aid for experienced Ideal reminders ... useful as an aid for experienced user BUT are not a replacement for manualsuser BUT are not a replacement for manuals

Choose appropriate mediaChoose appropriate media


Online vs paper-based documentationOnline vs paper-based documentation Online easier to distribute and maintainOnline easier to distribute and maintain Printing costs reducedPrinting costs reduced Online enables different search paths to the same Online enables different search paths to the same

informationinformation Easier for user to become disorientedEasier for user to become disoriented Online documentation must be written differentlyOnline documentation must be written differently Online documentation must be consistent with paper-Online documentation must be consistent with paper-

based documentationbased documentation


Reference AidsReference Aids Information contained in a large, complex Information contained in a large, complex

document is often inaccessibledocument is often inaccessibleUse:Use:

GlossariesGlossaries Indexes (very important)Indexes (very important) Contents pageContents page OthersOthers

Numbering systemsNumbering systemsPage, Sections, paragraphs, itemsPage, Sections, paragraphs, itemsSection dividers - tabbed card, coloured pages, Section dividers - tabbed card, coloured pages, Section/chapter summariesSection/chapter summaries


Colour and graphicsColour and graphics

Use a minimum number of coloursUse a minimum number of colours Be consistent and familiar (eg. red for hot) in your use Be consistent and familiar (eg. red for hot) in your use

of colour codesof colour codes Don't rely on colour alone to discriminate between itemsDon't rely on colour alone to discriminate between items

Graphics can make a document more effective:Graphics can make a document more effective:points in a text can be emphasisedpoints in a text can be emphasisedcan increase reader's interestcan increase reader's interestcan replace, clarify or simplify the textcan replace, clarify or simplify the text


Layout and PaginationLayout and PaginationLayout:Layout:

Be consistent in your layout Be consistent in your layout Use type size (at least 4 points different) or Use type size (at least 4 points different) or

bolding to indicate relative importance or bolding to indicate relative importance or weightweight

Page:Page:Use a page size suited to the environment Use a page size suited to the environment

that the document is going to be used inthat the document is going to be used inMake sure page numbering is clearMake sure page numbering is clear


Planning a Cost-time Schedule for Planning a Cost-time Schedule for documentationdocumentation

Why? - Often documentation is forgotten, ignored or dismissed Why? - Often documentation is forgotten, ignored or dismissed as not being important.as not being important.

Aim - to develop an estimate of the time required for Aim - to develop an estimate of the time required for documentation DURING development .. not a trivial task.documentation DURING development .. not a trivial task.

Time vs Cost - be realistic about your estimates .. Time vs Cost - be realistic about your estimates ..

Time saved in the documentation task will be wasted many Time saved in the documentation task will be wasted many times over explaining things not included or not clearly times over explaining things not included or not clearly described in the documentation provided.described in the documentation provided.

Monash University, SIMS, Semester One, 2005

23

Specify the document

Draft and edit the document

Review the document

Publish the document

Maintain the document

Not OK

OK

The Documentation Process


EffectiveEffective documentationdocumentation check check listlist

Objective clearly statedObjective clearly stated Target audience identifiedTarget audience identified Consistent approach used (wording, structure, Consistent approach used (wording, structure,

layout) - templates helplayout) - templates help The principles of documentation organisation The principles of documentation organisation

and development have been followed and development have been followed Maintenance process in placeMaintenance process in place Put yourself in the users’ position - can you Put yourself in the users’ position - can you

easily find what you’re looking for?easily find what you’re looking for?


ReferencesReferences

DWYER, J. (1997) The Business Communication Handbook (4DWYER, J. (1997) The Business Communication Handbook (4thth edition) Prentice-Hall, New York, N.Y. edition) Prentice-Hall, New York, N.Y.

ANDERSON, P.V. (1995). ANDERSON, P.V. (1995). Technical writing: A reader-centred Technical writing: A reader-centred approachapproach, 3rd ed. Harcourt, Brace & Co., Fort Worth., 3rd ed. Harcourt, Brace & Co., Fort Worth.

BROCKMAN, J. R. (1990). BROCKMAN, J. R. (1990). Writing better computer user Writing better computer user documentation - From paper to hypertextdocumentation - From paper to hypertext. John Wiley and . John Wiley and Sons, Inc., New York.Sons, Inc., New York.

Documents

CSE1204 - Information Systems 1 Communication and documentation during systems development