Proposed new international standard for user documentation

There is already an international standard for user documentation: IS15910 "Software user documentation process" has been around for some years, and is widely used in Australia and elsewhere.  It was based closely on an original Australian Standard AS4258, developed here from scratch.  Phil Cohen, who chaired the Standards Australia committee that developed AS4258, is one of the Principals of HCi.

Phil was also closely involved in the migration of the Australian 4258 to the ISO standard IS15910, and in fact was Editor for the new international standard.

IS15910 is a 'mandateable' standard - it's intended to be called up in a contract.  It sets out the contractual requirements on an organisation which produces user documentation, and specifies the way in which the documentation development should be planned.  Naturally, HCi's own documentation methodology fully complies with IS15910.

The same international standards committee that developed IS15910 is now involved in the development of a companion standard, 18109, which will be titled "Software and systems engineering - Guidelines for the design and preparation of user documentation for application software".  The major difference between this new standard and IS15910 is that the new document is not 'mandateable'; it's intended to be used not like a contract, but like a textbook.

It sets out in detail the use of the key element in documentation design: audience and task analysis.  Again, HCi's methodology has been based on this for some years.

The new standard is currently in an advanced draft, but is not due for publication in Australia until 2003 ... standards take a long time to develop; the original AS4258 took nearly a decade.

However, to give you an idea of the coverage of the standard, we've included a draft table of contents from the current version.

All Australian and international standards can be purchased from Standards Australia online.

1 Scope

2 Terms and definitions

3 Overview

3.1 Forms of documentation

3.2 Deciding what form of documentation to use

3.2.1 General

3.2.2 Information that needs to be on the screen

3.2.3 Information that needs to be on paper

3.3 Types of guidance provided

3.3.1 Process guidelines

3.3.2 Design guidelines

4 Objectives (Process)

4.1 General

4.2 Collect and interpret project requirements and constraints

4.2.1 General

4.2.2 Product objectives

4.2.3 Sales objectives

4.2.4 Schedule objectives

4.2.5 Usability objectives

4.2.6 Modification requirements

4.2.7 Internationalisation and national cultural requirements

4.2.8 Translation requirements

4.2.9 Packaging requirements

4.2.10 Legal requirements

4.2.11 Security

4.2.12 Standards and conventions

4.2.13 Cost constraints

4.2.14 Documentation delivery and viewing mechanisms

4.2.15 Quality management

4.2.16 Provision of technical information

4.2.17 Approval authorities

4.2.18 Change control

4.2.19 Availability of resources

4.3 Documentation proposal

5 Analysis and design (Process)

5.1 Audiences

5.1.1 Audience analysis

5.1.2 Learning stages ad frequency of use

5.1.3 Working environments

5.1.4 Audience profiles

5.2 Tasks

5.2.1 Task analysis

5.2.2 Mapping audiences to tasks

5.2.3 Task characteristics

5.2.4 Task profiles

5.3 Information

5.3.1 Information needs

5.3.2 Context of use

5.3.3 Volume/amount of documentation

5.3.4 Media

5.3.5 Information profile

5.4 Usability

5.4.1 Define usability goals

5.4.2 Record usability goals

5.5 Document suite structure

5.5.1 General

5.5.2 Option 1: Group information needs into documents

5.5.3 Option 2: Choose document types

5.6 Individual document structures

5.6.1 Prepare draft tables of contents

5.6.2 Define the document structure

5.7 Document writing style guides

5.7.1 General

5.7.2 General advice

5.7.3 Awareness and appreciation documents

5.7.4 Installation instructions

5.7.5 Tutorial documents

5.7.6 Quick reference documents

5.7.7 Comprehensive reference documents

5.7.8 Diagrams

5.7.9 Graphs and charts

5.7.10 Illustrations of screen displays

5.7.11 Illustrations of printed output

6 Planning (Process)

6.1 General

6.2 Document plan

6.2.1 General

6.2.2 Standards

6.2.3 Version control and change control

6.2.4 Personnel

6.2.5 Equipment

6.2.6 Responsibilities

6.2.7 Estimate costs

6.2.8 Prepare schedules

6.2.9 Prototypes and drafts

6.2.10 System tests

6.2.11 Reviews

6.2.12 Usability testing

6.2.13 Localisation and customisation

6.2.14 Approval

6.2.15 Maintenance, updating and future developments

6.3 Review and detailed documentation plans

7 Development and review (Process)

7.1 General

7.2 Prepare and issue draft(s)

7.3 Check and review drafts

7.3.1 General

7.3.2 Reviewing the information

7.3.3 Usability tests

7.3.4 System tests

7.3.5 Validation and field trials

7.4 Prepare subsequent drafts

7.5 Prepare document masters

7.6 Handing over the finished documentation

7.7 Localisation and customisation

7.8 Archiving

8 Evaluation and updating (Process)

8.1 General

8.2 Evaluate the documentation

8.3 Update the documentation

9 Design of documentation (Guidelines)

9.1 Introduction

9.2 Use of colour

9.3 Presentation of text

9.3.1 Typefaces and sizes

9.3.2 Use of bold and italic type

9.3.3 Lines of text

9.3.4 Vertical spacing

9.3.5 Headings in text

9.3.6 Highlighting

9.3.7 Lists

9.3.8 Tables

9.3.9 Boxes and borders

9.3.10 Annotations

9.3.11 Representing the software display information

9.3.12 Representing information that the uses need to type in

9.3.13 Representing individual keyboard keys

9.3.14 Variables

9.3.15 Emphasising words and terms

9.4 Product copyright and version details

9.5 Overview of the documentation

9.6 Process descriptions

9.7 Task Descriptions

9.8 Explanations of fields and options

9.9 Names and uses of user interface options

9.9.1 Names

9.9.2 Uses

9.10 Description of application functions

9.11 Notes, cautions and warnings

9.12 Definitions of terms

9.13 Concepts

9.14 Exploitation information

9.15 Frequently asked questions

9.16 User supplied contents

9.17 Navigation

9.17.1 Introduction

9.17.2 Accessing on-screen information

9.17.3 Finding the right information - linking information in on-screen documentation

9.17.4 Indexes

9.17.5 Knowing what the current information is

9.17.6 Knowing the current position within a topic

9.17.7 Finding the same information again

9.17.8 Switching between the application and the documentation

9.17.9 Printing information

9.17.10 Moving to a different topic

9.17.11 Obtaining clarification or amplification of current information

9.17.12 Browsing through information

9.17.13 Viewing topics in order

9.17.14 Exiting from the on-screen documentation

9.17.15 Finding user-supplied information

9.17.16 Sizes of topics and fragments

9.18 Presentation

9.18.1 Introduction

9.18.2 Windowing

9.18.3 Layout and grids

9.18.4 Colour

9.18.5 Controls

9.19 Icons and signposts

9.19.1 When to use icons and signposts

9.19.2 Design of icons and signposts

9.19.3 Displaying the names of icons

9.20 Presentation of illustrations

Annex A (Informative) Process Checklists

A.1 Objectives

A.2 Planning

A.3 Analysis

A.4 Design

A.5 Implementation

Annex B (Informative) Content Checklist

B.1 Content checklist

B.2 Navigation checklist

B.3 Style checklist

B.4 Presentation checklist

Annex C (Informative) Evaluation of on-screen information

C.1 General

C.2 Procedure

C.3 Viewpoints

C.4 Qualities

C.5 Evaluation methods

Annex D (Informative) Document writing style and techniques

D.1 General

D.2 Conventions

D.3 Vocabulary

D.4 Terminology

D.5 Writing styles

D.5.1 General

D.5.2 Instructions

D.5.3 Descriptions and explanations

D.5.4 Facts

D.6 Writing techniques

D.6.1 General

D.6.2 Paragraphs

D.6.3 Sentences

D.6.4 Conditions

D.6.5 Active and passive voice

D.6.6 Tenses

D.6.7 Singular and plural verbs

D.6.8 Punctuation

D.6.9 Hyphenation

D.6.10 Infinitives

D.6.11 Capital letters

D.6.12 Messages

D.6.13 Anthropomorphisms

D.6.14 Analogies and metaphors

D.7 Lists

D.8 Tables

D.9 Illustrations

D.9.1 When to use an illustration

D.9.2 Types of illustration

D.9.3 Styles of illustrations

Annex E (Informative) Design and preparation of printed information

E.1 Introduction

E.2 Design

E.2.1 Decide how the paper documents will be produced

E.2.2 Hierarchic structure of documents in the form of books

E.2.3 Style and presentation

E.2.4 Production and distribution

This article may be reproduced only with the permission of HCi (email HCi ). Copyright HCi, 2001.