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

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.

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

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.

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.

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

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 notifications, Incident 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.