IMS9001 - Systems Analysis and Design

1. IMS9001 - Systems Analysis and Design Communication and Documentation: Additional Notes on Documentation

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

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

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

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

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

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

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

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

10. 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 ?

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

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

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

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

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

16. 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 • 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. Point of eye's exit on page

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

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

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

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