Raising the standards

Experts from around the world produced a new ISO standard for technical documentation in 2004: Guidelines for the design and preparation of user documentation for application software. Mike Unwalla of TechScribe was a member of the editing team. Here, he outlines what the standard contains and how it was produced.

Scope of the standard

The international standard describes how to:

Determine what information users need
Determine the way that the information should be presented
Prepare the information
Present the information.

The standard is not prescriptive. It does not say that there is just one right way of doing things all the time. Rather, it makes recommendations. The writer of the documentation must use judgement about what is best for the intended audience.

Contents of the standard

These are some of the most important topics with which the standard deals:

Forms of the documentation. What needs to be on paper, and what needs to be online.

Defining objectives. Product, usability, sales, accessibility, cost constraints, packaging, approval and so on.

Analysis and design. Who are the users? What tasks do they perform? Defining the overall documentation suite.

Planning. Documentation plan, personnel, costs, equipment, schedules and so on.

Development and review. Preparing and issuing drafts, reviews, usability testing, preparation of document masters, handing over the finished documentation, localisation, archiving.

Guidelines for the design of the documentation. Overviews, task descriptions, definitions, error messages, navigation, colours, text, graphics and illustrations.

A useful feature of the standard is its use of checklists. These deal with processes that the writer needs to carry out, and also with the content of the user documentation itself.

Background to the standard

The ISO (www.iso.org) is a network of national standards bodies from 140 countries. For example, in the UK we have the BSI (www.bsi-global.com), the US has ANSI (www.ansi.org) and Germany has DIN (www2.din.de). These bodies work in partnership with international organisations, governments, industry, business and consumer representatives.

Two existing British Standards dealt with the design and preparation of documentation for users of application software (BS 7649:1993 and BS 7830:1996).

Many changes had taken place in IT since these standards were produced, and so a new standard was developed. It provides best practice for both online (on-screen) documentation and printed documentation.

Who produced the standard?

To answer the question of who produced the standard, we have to introduce some necessary jargon. The new standard (ISO/IEC 18019) was developed by Working Group 2 (Software Systems Documentation) of Sub-Committee 7 (Software and System Engineering) of Joint Technical Committee 1 (Information technology) of ISO and the IEC, or ISO/IEC JTC 1/SC 7/WG 2 for short!

The following diagram shows the relationship between the groups involved and the information that passed between them.

Organisational structure for ISO 18019

The standard progressed through a series of stages, which are explained in detail in the next section. Basically, at each stage, a document was produced by the Working Group. At the end of each stage, there was a ballot to determine whether the document should progress to the next stage. The ballot was performed by representatives of the national bodies that are members of ISO/IEC JTC 1/SC 7.

Every standard has a project editor who is responsible for implementing the changes agreed by the Working Group. In the case of ISO/IEC 18019, the project editor was supported by an editing team that was instructed and delegated by WG 2.

The Working Group met several times a year, in different countries to enable local experts to participate. Meeting times were determined by the ballot cycles, however, standards development often continued between meetings using email and conference calls.

How an international standard is produced

A document goes through many stages before it becomes an international standard:

A group of experts prepares a New Project proposal together with a Working Draft (WD), which is typically an outline of the structure of the standard. The WD can be an entirely new document, or it can be based upon an existing national or industry standard.
The proposal is subject to an international ballot of national bodies. If the proposal is approved, it is given a project number and allocated to a Working Group.
The Working Group develops a draft. When the Working Group considers the draft to be ready for public review a first Committee Draft (CD) is sent to the ISO/IEC organisation.
The ISO/IEC organisation distributes this document world-wide to national bodies.
The national bodies circulate copies to the individual reviewers within their country.
Each country's reviewers evaluate the content and send technical and editorial comments to their national body. Within a country, a special committee compiles and reviews those comments and agrees the voting position (that is, whether or not the document should progress to the next stage).
The national bodies send the final comments and votes to the Working Group through the ISO/IEC organisation.
The experts in the Working Group meet to analyse the national body comments and to consider the national body votes:
1. They produce a document called a disposition of national body comments. This lists all the technical and editorial comments, and whether they have been accepted or rejected (along with reasons).
  Note: In the case of ISO/IEC 18019, the editing team was instructed and delegated by WG 2 to review all the editorial and minor technical comments, update the draft standard and prepare the disposition of national body comments.
2. If the standard received the required number of positive votes from the national bodies, and if the Working Group considers that the changes due to technical comments do not invalidate the votes, the standard progresses to the Final Committee Draft stage.
3. If the standard does not receive the required number of positive votes from national bodies, or if the Working Group does not consider it to be suitable for progression, it is revised and the CD cycle is repeated until the document is approved.
  Note: If a standard is not progressed within certain time limits, it can be cancelled by ISO/IEC.
The review cycle repeats through:
1. Final Committee Draft. This is the last opportunity for national bodies to submit technical comments (in addition to voting and providing editorial comments).
2. Final Draft International Standard. The Final Draft International Standard ballot is a yes/no vote (plus editorial comments) on whether or not the standard should become a full International Standard.
Following a successful Final Draft International Standard ballot:
1. Final editorial changes are made to the draft.
2. The updated document is sent to ISO in Geneva for publication as a full International Standard.

Obtaining more information

BS ISO/IEC 18019:2004 'Software and system engineering. Guidelines for the design and preparation of user documentation for application software' is available from the British Standards Institution (www.bsi-global.com), IEEE (www.ieee.org) and other standards bodies.

Professional technical writers are invited to participate in the development of a new suite of international standards for technical communicators (www.hci.com.au/iso/project_11).