The development of ISO/IEC 18019:2004

Experts from around the world developed 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 explains what the standard contains and how it was developed.

Scope of the standard

The international standard explains how to:

Determine what information users need
Determine the way that the information is shown
Prepare the information
Present the information.

The standard is not prescriptive. The standard does not say that only one method is always correct. Instead, the standard gives recommendations. The writer of the documentation must use judgement about what is best for the 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. Categorizing the users (audience analysis). Finding the tasks that users do (task analysis). Defining the 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 completed documentation, localization, archiving.

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

Useful checklists give information about the processes that a technical writer needs to do and about the content of the user documentation.

Background to the standard

The ISO (www.iso.org) is a network of national bodies from 140 countries. For example, the UK has the BSI (www.bsigroup.com), the US has ANSI (www.ansi.org) and Germany has DIN (www.din.de). These national bodies work with international organizations, governments, and industry, business and consumer representatives.

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

After BS 7649:1993 and BS 7830:1996 were developed, there were many changes in IT. Therefore, a new standard was developed. It gives best practice guidelines for both online documentation and printed documentation.

Who developed the standard?

To answer the question of who developed the standard, we must use some technical terms. The new standard (ISO/IEC 18019:2004) 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 (ISO/IEC JTC 1/SC 7/WG 2).

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

Organizational structure for ISO/IEC 18019:2004

The standard progressed through a sequence of stages, which are explained in detail in the next section. At each stage, a document was developed by the Working Group. At the end of each stage, a ballot determined whether the document progressed to the next stage. The ballot was done by representatives of the national bodies that are members of ISO/IEC JTC 1/SC 7.

Each standard has a project editor who makes the changes that are agreed by the Working Group. In the case of ISO/IEC 18019:2004, 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 let local experts participate. Meeting times were dependent on the ballot cycles. However, standards development usually continued between meetings using e-mail and conference calls.

How an international standard is developed

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

A group of experts prepares a New Project proposal and a Working Draft (WD). Typically, a working draft is an outline of the structure of the standard. The working draft can be a new document, or it can use a 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 then given to a Working Group.
The Working Group develops a draft. When the Working Group thinks that the draft is ready for public review, a first Committee Draft (CD) is sent to the ISO/IEC organization.
The ISO/IEC organization sends the CD to national bodies.
Each national body sends a copy of the CD to each reviewer in the country.
Each country's reviewers evaluate the content and send technical and editorial comments to their national body. In each country, a special committee compiles and reviews the comments, and agrees on the voting position (that is, whether the CD progresses to the next stage).
The national bodies send the final comments and votes to the Working Group through the ISO/IEC organization.
The experts in the Working Group meet to analyse the national body comments and to consider the national body votes:
1. The Working Group writes a document called a disposition of national body comments, which contains all the technical and editorial comments. For each comment, a note shows whether it has been accepted or rejected. For important comments, reasons for the decision are given.
  Note. For ISO/IEC 18019:2004, 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 thinks that the changes because of 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 think that the CD is suitable for progression, the document is revised and the CD cycle is repeated until the document is approved.
  Note. If a standard is not progressed in 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 send technical comments (in addition to voting and supplying editorial comments).
2. Final Draft International Standard. The Final Draft International Standard ballot is a yes/no vote (plus editorial comments) on whether the standard becomes a full International Standard.
After 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.

Getting more information

In 2008, ISO/IEC 18019:2004 was replaced by ISO/IEC 26514:2008. You can buy ISO/IEC 26514:2008 from British Standards Institution (www.bsigroup.com) and other national bodies.