DOCUMENTATION REF: Essentials of IT (Hamilton et al) Chapter 1

Contents 4 Types of documentation 4 Documentation media

Resources needed 4 Figures –1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9

Documentation 4 “Communication designed to ease the interactions between computer software and the individuals who manage, audit operate or maintain it.” 4 eg printed instructions, CD-ROM

Types of documentation 4 Technical documentation 4 User documentation

Technical documentation 4 “Printed or on-line information that describes the construction of the computer (ie, the hardware) or the software that runs the computer.” 4 Usually features combinations of text and diagrams 4 Developed and used by technical people 4 eg Cabling specifications and requirements

User documentation 4 “Printed or on-line documentation that assists people (the users) to use the computer system” 4 Usually consists of text and diagrams 4 Three main types –instructional material –training material –policy and procedures documents

Instructional material 4 Accompanies the computer system 4 Provides information for the user on how to use the system or a particular part of it 4 eg How to assemble a computer 4 eg Shutting down the computer

Training material 4 Aims to teach people how to use a computer system, usually a software application 4 It can be used for self-study or as a resource by a trainer 4 eg how to use word processing software

Policy and procedures documents 4 Describe organisational rules and guidelines 4 Explain how to do particular jobs 4 Helpful for new employees 4 Valuable reference if something unusual happens 4 Assist with quality assurance - to see if standard procedures are being followed 4 eg ISP policy document

Media for documentation 4 Paper or On-line 4 Choice is determined by many factors: –usability (how well it helps the user) –nature of the user’s needs –appropriateness of the medium to the task

Paper-based (print) documentation 4 Manuals, reference guides, brochures 4 Most widely used user documentation, so people are most familiar with it 4 Can detail things such as: –features or functions of HW/SW –how to install or setup HW/SW –how to operate HW/SW –what to do, who to call if things go wrong

4 Word processing and DTP software have made preparation of printed documentation much easier 4 eg How to use Getting started

On-line documentation 4 Uses computer technology itself to deliver the user documentation 4 Most familiar are user messages, on-line help, tutorials, manuals 4 eg On-line guide contents 4 Includes: Hypertext, Wizards, Multimedia, CD-ROM

Hypertext 4 Uses ‘hotspots’ on the screen which contain links to other information about the word or picture being pointed to 4 Can be a ‘pop-up’ windows or another page of text 4 eg serial port information

Wizards 4 Instructions are presented automatically on screen for the user to follow 4 Leads the user through a set of steps to perform some task 4 May ask the user for input, then use that information to automatically do a task 4 eg chart wizard in Excel

Multimedia 4 Combination of text, graphics, video, animation, sound and interactivity 4 information can also be organised as a database so data can be retrieved quickly and accurately

CD-ROM 4 Have overcome storage limitations for on- line documentation 4 Provide a cheap and flexible way of providing documentation 4 Good for documentation that contains a large amount of information

Purpose of documentation 4 Generally, the purpose of documentation is to provide communication 4 Technical and user documentation have different purposes

Purpose of technical documentation 4 To provide information for people who build and maintain computer systems 4 Used by : computer engineers, computer technicians, systems analysts, data analysts, programmers, technical writers, software testers, project managers, system managers, computer operators 4 they need to know how a system, or part of a system, works

Examples 4 Data analyst - data dictionary 4 programmer - program specifications 4 software tester - samples of typical data 4 technical writer - screen and report layouts

Purpose of User documentation 4 To help people use the computer system 4 Gives support to users in order to: –learn to use the system (HW/SW) –understand the functions and purpose of the software application –refer to specific functions 4 users will resist using such documentation if it is difficult to read or understand

GUIs 4 To overcome resistance to reading documentation, software developers have made software interfaces more ‘intuitive’ - GUI 4 Features of a GUI: –standard navigation techniques and tools (eg mouse, scroll bars, cursor keys) –visual clues or information (eg icons, buttons) –standard ways of accessing information or functions (eg pull-down menus, on-line help, status bars, prompts) –multiple windows for related information

4 User actions should be simple, obvious, consistent and logical 4 good GUI design should reduce the need for other documentation 4 Intuitive systems may not suit everybody, therefore some additional documentation will always be necessary

Individual differences 4 Developers of documentation need to take individual differences into account in order to satisfy the maximum number of users: –personalities –experience –culture –education