ISO/IEC/IEEE 15289: Clarity at Last for Software Documentation?

The title of ISO/IEC/IEEE 15289 is “Systems and software engineering — Content of life-cycle information items (documentation)”.

As the title suggests, it establishes specifications for the content of software documentation. This makes the standard ideal for:

  • Helping with the implementation of other standards, such as ISO/IEC/IEEE 12207:2017 and IEC 62304
  • Checking conformity with these standards
  • Identifying the documents required for the software documentation
  • Defining the contents of these documents

This means that ISO/IEC/IEEE 15289:2019 is a standard that affects every organization that develops software.

1. Overview of ISO/IEC/IEEE 15289

a) Target group: who should read the standard?

The standard is aimed at people involved in software documentation in the following roles:

Role

Responsibilities in the context of ISO/IEC/IEEE 15289

Project manager

Defining the information management process

Determining the documentation requirements (and therefore the documents and their content)

Buyer (of the software)

Defining the requirements for the documentation that the manufacturer must produce

Developer (e.g., architecture, implementation, testing)

Writing the software and systems development documentation

Quality manager

Checking conformity with standards (ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288 are mentioned in this regard)
Improving the quality of processes, devices and services

b) Section structure of ISO/IEC/IEEE 15289

ISO/IEC/IEEE 15289:2019 contains 10 sections across 86 pages.

You can download the mind map as a PDF here:

ISO-IEC-IEEE-15289-2019Download

The following table gives an overview of the individual sections of the standard.

Section

Title

Summary

1

Scope

The standard wants to describe the content of all documents in a software documentation but not a management system

2

Normative references

References to ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288

3

Terms, definitions and abbreviated terms

29 definitions. But the document classes are only defined for the first time in section 7

4

Applicability

Purpose, intended users, applicability (software systems and software projects of all kinds)

5

Conformance

The standard can be used to check conformity with ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288

6

Life-cycle data and information items

General requirements for documents and records and the difference between them. See section TODO

7

Generic types of information items

Overview of seven document classes and their generic content (see below)

8

Mapping of information items to the life cycle processes

Mapping to the standards ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288

9

Records

Specific information on records, which the standard interprets slightly differently to ISO 9000

10

Specific information item (document) contents

Specific guidance for individual document types, e.g., “software architecture description”

2. Requirements for documents

a) General requirements

In section 6, ISO/IEC/IEEE 15289 describes the general requirements for documents:

  • Clarity
  • Completeness
  • Verifiability
  • Consistency
  • Modifiable
  • Traceability
  • Presentability

Tip

The Johner Institute recommends creating specific documentary requirements in work instructions and checklists for the document review. For example, for a software requirements specification, checking whether the runtime environment has been defined based on the hardware and operating system (including version) should be explicitly required.

b) Meta-level requirements

Additional requirements for documents at the meta-level are:

  • All information/documents to be managed are identified (e.g., lists of all documents).
  • The form in which the information should be presented has been defined (e.g., text, graphics, in databases).
  • The status of the documents/information is identifiable.
  • The information/documents are actually available to the intended stakeholders.

 Additional information

ISO 15289 is not specifically about document control. Read more on the topic of document control here to comply with the requirements of ISO 13485, among others.

c) Content requirements

ISO 15289 establishes the requirements for specific documents at two levels:

  1. First, it assigns each document to a document class, which it calls “Generic types of information items”. It specifies the contents for each document class. This article provides an overview of the seven document classes below.
  2. The standard adds additional content for each specific document (e.g., a software architecture). The next section gives a specific example.

3. Document classes and generic content

a) Documents

In section 10, ISO/IEC/IEEE 15289 describes a total of 74 document types, such as Release Plan or System architecture description. The standard splits all these document types into seven document classes. However, it does not use the term document class, preferring to use the term Generic type of information items.

#

Document class

Description

Examples

1

Description

Representation of a planned or actual function, service, product, component, etc.

Software architecture, service catalog, operational concept

2

Plan

Defining when and how specific processes or activities will be carried out and by who

V&V plans, software development plan, risk management plan

3

Policy

Defining the top-level aims of an organization to achieve specific goals

Quality policy, risk policy (although is not specified by ISO 15289)

4

Procedure

Detailed definition of when and how a certain process, a certain activity or task should be carried out, including, if applicable, the tools

Instructions for use, test instructions, SOP on processing complaints

5

Report

Description of the results of activities

Test report, problem report, incident report, review minutes

6

Request

Information to ask for a response or reaction

Change request, customer satisfaction survey, RFP (request for proposal)

7

Specification

Requirements for a service, product or process

Contract, software requirements specification, SLA

The standard specifies the generic content for each of these document classes. Therefore, for example, a document in the “Description” class must contain at least the following information:

  • Date and status
  • Scope
  • References
  • Notation used
  • Summary
  • Glossary
  • Change history

Section 10 of ISO 15289 then adds additional content for each specific document. For example, a software architecture, which falls into the “Description” document class must also contain:

  • One or more architectural views
  • A system concept in terms of purpose and non-functional properties such as safety, interoperability and security
  • Constraints (solution space limitations)
  • Design decisions and justifications

 Additional information

A software architecture has to implement a lot of non-functional software requirement specification requirements. ISO 25010(german) provides an overview of non-functional requirements.

b) Records

Definition

In addition to the documents and document classes (Generic types of information items), ISO 15289 also refers to Records. However, the standard understands the term records slightly differently to ISO 9000 and, as a result, also uses the terms records of data and data records.

These data records are more reminiscent of raw data in databases, registers or repositories. Records as defined by ISO 15289 contain the factual data (e.g., lists of test results in a test database) that are then turned into records as defined by ISO 9000.

A (final) test report would, therefore, already be a record.

Content

ISO 15289 also establishes the standard content for records

  • Date and status of the record
  • Scope
  • Subject or category
  • Issuing organization
  • References
  • Content
  • Unique identification

For these records, ISO 15289 maps to the requirements of ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288 in the same way as it does for documents.

4. Mapping to IEC 62304

Medical software developers who follow IEC 62304 can also benefit from the specifications of ISO 15289. To do this, it is necessary to map the content required by IEC 62304 onto the document types listed in ISO 15289.

Section of IEC 62304

Required content

Documents according to ISO 15289

Section of ISO 15289

5.1

Software development plan

Development plan

Project management plan

Release plan

Quality plan

10.16

10.42

10.47

10.44

5.1

Software risk management planning

Risk management plan (not 100% equivalent)

10.52

5.1

Documentation planning

Information management plan

Information management procedure

10.27

10.28

5.1

Software configuration management planning

Configuration management plan

Configuration management procedure

10.9

10.10

5.2

Software requirement analysis

System requirements specification

If necessary, interface description

10.60

10.28

5.2

Installation requirements

Operational concept

10.35

5.2

Re-evaluate medical device risk analysis

Risk action request

10.51

5.2

Verify software requirements

Verification procedure

Verification report

10.73

10.74

Example mapping of IEC 62304 and ISO 15289

ISO 15289 is not just helpful for development documentation according to IEC 62304 section 5. It also provides an overview of additional life-cycle documents, some of which IEC 62304 only lists rudimentarily in sections 7 to 9.

5. Conclusion, summary

ISO/IEC/IEEE 15289 is a useful standard:

  • It provides an overview and clarity
    It provides clarity through concepts such as document classes and, as a result, reduces the feeling of drowning in a sea of documents.
  • It helps you to not forget anything and acts as a basis for testing
    The standard lists the documents that organizations that develop software usually work with. It also provides requirements for the content of each document type. This means it can be used as a checklist for project managers, quality managers and auditors.
  • It provides guidance when creating documents
    New companies in particular don’t know what content needs to be documented, how to divide this content across documents, and how to structure these documents. This doesn’t just apply to the development of software systems, it also applies to their operation. ISO 15289 provides specific guidance for both.
    User notificationsIncident management procedures and Transition plans are examples of documents that are not directly related to development.

Established companies can also benefit from the standard, particularly if their documentation processes have become a bit chaotic over the years with redundant or superfluous content.


The Johner Institute helps medical device manufacturers whose devices contain software or are software create legally compliant software and review before audits. Get in touch with us (e.g., via our web form) to find out how you can establish lean, precise and compliant documentation that will make you shine in audits and reviews.

Auditgarant contains a comprehensive set of templates for software documentation to ensure compliance with ISO 62304 and ISO 13485 and avoid problems during medical device authorizations.

Author:

Prof. Dr. Christian Johner

Starter-Kit_rot_dunkel

A quick overview: Our

Starter-Kit

Learn More Pfeil_weiß
blog_rot_dunkel

Always up to date: Our

Institutejournal

Learn More Pfeil_grau