Documentation of Product and Process

Artefacts

“We favor working software over comprehensive documentation”, Agile Manifesto, 2001.

The above statement from the Agile Manifesto means that executable and functioning products/software/systems are more important than documentation. However, this does not mean that documentation is unimportant and can be omitted completely. An important criterion for documents is therefore that they are needed, especially whether they are also read, i.e. whether there is a real stakeholder need behind them. In regulated system developments, the documents to be created and their content are specified. Of course, these must also be created and delivered when using an agile development method. The difference lies in the iterative-incremental creation of the documents in parallel with the product to be developed. As this results in many versions of the various documents, the documents must be versioned properly. The associated release process must also be simple and uncomplicated.

A fundamental question is what types of documentation are required and how we map the creation of the documents in our development process.

Types of Documents

  1. Prozessdokumentation:
    • Prozessbeschreibung und Leitfäden, auch Standard Operating Procedures (SOP)
    • Dokumentenvorlagen für die Produktdokumentation (Templates)
    • Prozess-Reviews und Audit-Reports
  2. Produktentwicklungsdokumentation:
    • Planungsdokumente
    • Statusreports
  3. Produktdokumentation:
    • Produktdokumentation folgt immer der Systemarchitektur und seinen Systemelementen, Modulen, Schnittstellen und Integrationsebenen
    • Spezifikationen (Anforderungen, Lösung, Tests)
    • Dokumentierte Entscheidungen (z.B. in Form eines Produkt-Design-Journals)
    • Testergebnisse und Reports
    • Freigaben und Zulassungen
    • Benutzerdokumentation (Use-Case-basiert oder Komponenten-basiert)

 

  1. Process documentation:
    • Process description and guidelines, including Standard Operating Procedures (SOP)
    • Document templates for product documentation (templates)
    • Process reviews and audit reports
  2. Product development documentation:
    • Planning documents
    • Status reports
  3. Product documentation:
    • Product documentation always follows the system architecture and its system elements, modules, interfaces and integration levels
    • Specifications (requirements, solution, tests)
    • Documented decisions (e.g. in the form of a product design journal)
    • Test results and reports
    • Releases and approvals
    • User documentation (use case-based or component-based)

In principle, the P4 framework regards the required documents as delivery objects, just like other “parts” of the system, such as the production tooling and test tools. It is therefore important to determine at the beginning of each product development which delivery objects should be created in addition to the product to be developed. The norms and standards to be complied with sometimes provide important information about the form and content of the documents, e.g. the ISO/IEC 13485, 14971, 60601 and 62366 standards in medical technology.

Many of the documents to be created are closely coupled  to the product to be developed, its components and their integration. These should then also appear in the Definition of Done of the maturity level of the respective system element (which incidentally describes the development process to a large extent). This creates an object-oriented backlog and document structure. The advantage of this is that the product, the components and the integrations are only considered complete when the associated documentation has also been created and released at the intended level of maturity. This prevents rather damaging re-documentation.

Development documentation is therefore created iteratively and incrementally, synchronized with the product and its components!

“Make is as simple as possible, but not simpler”, Albert Einstein.

Due to the rigid specifications, developers often see the documents they create as a chore. This should not and does not have to be the case. The process experts and developers should therefore design the documents in such a way that they are created as they work, so to speak, and thus represent a real working tool. This means that the tools for document creation must be easy to use and ideally perform tedious tasks automatically.

Reuse

Dokumente eignen sich sehr gut zur Wiederverwendung, insbesonders da sie heute meist in digitaler Form vorliegen. Die einfachste Form der Wiederverwendung stellt die Nutzung von Dokumentenvorlagen (Templates) dar. Meist werden diese Templates bei der Implementierung von Prozessstandards in einer Organisation erstellt und bestehen aus Dokumenten mit Kapitelüberschriften und ggf. ein paar Anweisungen zum Befüllen der Kapitel. Typischerweise müssen die Bearbeiter in den Projekten, dies Kapitel dann manuell ausfüllen, wobei übergreifende und einleitende Beschreibungen häufig aus anderen Dokumenten kopiert werden. Dies erzeugt Redundanzen, die bei jeder Überarbeitung angepasst werden müssen.

Diagrams as documentations

“A picture replaces a thousand words”, unknown.

Documents are created as lean as possible and through visualizations (e.g. using UML diagrams), ideally with added links to the visualized elements.

Automation

“Don’t Repeat Yourself”: The DRY principle.

When creating documents, care must be taken to avoid repetitions (DRY principle) in order to avoid having to find and maintain redundancies in the event of changes. Generating documents from a set of master data is a good technique for this. The Docs-as-Code approach takes this further and treats documents like software code, which is created and expanded in small steps, versioned and included and always kept up to date.

Frequency of document changes

One of the most important principles of agile product development is the iterative and incremental approach and being verifiable or even potentially deliverable as early as possible. This means that product functions (features & capabilities) are developed one after the other over time, i.e. they are added. It is necessary for the documentation associated with the product to be created in the same way in order to have complete documentation for a version of the product (aka release). This means that the product or system is complete after each iteration or cycle. The scope and maturity of product documentation can be defined by the type and frequency of releases (e.g. internal test releases or external releases for customers).

Now we can decide for the product documentation whether it belongs to the system like a module (and we consider it as a separate deliverable), or whether we consider the necessary documentation in the Definition of done for the system or its modules.

There will also always be documentation that belongs to a partial integration or the fully integrated system on the basis of the integrated modules, e.g. module specifications or test specifications and reports for partial integrations.

Life cycles of documentations

Iterative-incremental document adaptation does not mean that all documents should change constantly. There are basically three different change cycles with different frequencies:

  1. Change for process adaptations. If possible, these should only be adopted for new product developments
  2. Changes for new product developments or new applications
  3. Changes for functional enhancements to an existing product or in an ongoing product development (external or internal release)