Systems and software engineering - Requirements for designers and developers of user documentation

This clause presents the scope, purpose, organization, and candidate uses of this International Standard.

This International Standard supports the interest of software users in consistent, complete, accurate, and usable documentation. It includes both approaches to standardization: a) process standards, which specify the way in which documentation products are to be developed; and b) documentation product standards, which specify the characteristics and functional requirements of the documentation.

The first part of this International Standard covers the user documentation process for designers and developers of documentation. It describes how to establish what information users need, how to determine the way in which that information should be presented to the users, and how to prepare the information and make it available. It is not limited to the design and development phase of the life cycle, but includes activities throughout the information management and documentation processes.

The second part of this International Standard provides minimum requirements for the structure, information content, and format of user documentation, including both printed and on-screen documents used in the work environment by users of systems containing software. It applies to printed user manuals, online help, tutorials, and user reference documentation. This International Standard neither encourages nor discourages the use of either printed or electronic (onscreen) media for documentation, or of particular documentation development or management tools or methodologies.

This International Standard may be helpful for developing the following types of documentation, although it does not cover all aspects of them:

- documentation of products other than software;

- multimedia systems using animation, video, and sound;

- computer-based training (CBT) packages and specialized course materials intended primarily for use in formal training programs;

- documentation produced for installers, computer operators, or system administrators who are not end users;

- maintenance documentation describing the internal operation of systems software;

- documentation incorporated into the user interface itself.

This International Standard is applicable to documentation designers and developers, including a variety of specialists:

- information designers and architects who plan the structure and format of documentation products in a documentation set;

- usability specialists and business analysts who identify the tasks that the intended users will perform with the software;

- those who develop and edit the written content for user documentation;

- graphic designers with expertise in electronic media;

- user interface designers and ergonomics experts working together to design the presentation of the documentation on the screen.

This International Standard may also be consulted by those with other roles and interests in the documentation process:

- managers of the software development process or the documentation process;

- acquirers of documentation prepared by suppliers;

- usability testers, documentation reviewers, subject-matter experts;

- developers of tools for creating on-screen documentation;

- human-factors experts who identify principles for making documentation more accessible and easily used.

This International Standard is intended for use in all types of organizations, whether or not a dedicated documentation department is present, and may be used as a basis for local standards and procedures. Readers are assumed to have experience or knowledge of software development or documentation development processes.

Users of this International Standard should adopt a style manual for use within their own organizations to complement the guidance provided in the annexes to this International Standard, or adopt an industryrecognized style guide. Annex A provides guidance for the content of a style guide, and Annexes B and C provide guidance on style.

The order of clauses in this International Standard does not imply that the documentation should be developed in this order or presented to the user in this order.

In each clause, the requirements are media-independent, as far as possible. Requirements specific to either print or electronic media are identified as such, particularly in Clause 12. Annex D provides guidance for the design of printed documentation.

The checklists in Annex E may be used at each phase of the documentation process to check that the appropriate steps have been carried out and that the finished documentation satisfies quality criteria.

The checklists in Annexes F and G may be used to track conformance with the requirements of this International Standard for documentation processes and products.

The bibliography lists works that provide guidance on the processes of managing, preparing, and testing user documentatio