Documentation from the model

Evidence & Audit

This chapter describes, how documentation is created in Selmo and why it does not have to be created or maintained manually.

Documentation in Selmo is:

• no additional effort

• not a separate document

• not a subsequent result

But:

A structured view of the formal model.

---

The fundamental problem of classic documentation

In classic automation projects, documentation is often:

• temporally downstream

• decoupled from the code

• incomplete or out of date

• hard to trace

Typical situations:

• the code works, the docs are outdated

• changes are not applied consistently

• behavior cannot be conclusively proven

• audit questions must be interpreted

The problem is not a lack of diligence, but the lack of a common source of truth.

---

The model as the single source

In Selmo the model is that source.

The model already contains:

• process (sequences, states)

• Structure (plant, hardware zones, zones)

• behavior (Bit-Control)

• Monitoring (interlocks, CMZ, checks)

• reactions (stop, release, diagnosis)

That provides everything that is necessary for documentation.

What is described in the model, can be documented. What is not modeled, cannot be documented.

---

Which documentation is generated from the model

From the model the following can be automatically derived:

• Process descriptions → states, transitions, sequences

• Structure overviews → plant, hardware zones, sequences, zones

• Safety arguments → interlocks, CMZ, plausibility checks

• Diagnostic descriptions → zones, expectations, deviations

• Operating concepts → manual and automatic operation, HMI semantics

This documentation is:

• consistent

• up-to-date

• unambiguously

• fully traceable

---

Traceability and audit

Through the formal model it is always traceable:

• which state is active

• which conditions apply

• which monitoring applies

• why a reaction occurs

For audits this means:

• no interpretation of code

• no assumptions about behavior

• no detached descriptions

Instead:

An explicit, verifiable behavior model.

---

Documentation and changes

Changes are made in Selmo:

• to the model

• not to individual documents

This means:

• every change is central

• all derivations remain consistent

• no diverging document versions

Change in the model = change in code, diagnostics and documentation.

---

Distinction from classic documents

To clarify:

• Documentation ≠ PDF

• Documentation ≠ textual description

• Documentation ≠ collection of comments

Documentation is:

a formal representation of the model from different perspectives.

---

Benefits of model-based documentation

Through model-based documentation the following becomes:

• engineering more transparent

• operation safer

• commissioning more efficient

• auditing easier

• responsibility provable

Documentation becomes from a mandatory document an integral part of the system.

---

Summary

Documentation in Selmo:

• is generated automatically from the model

• is always up to date

• is clearly traceable

• supports evidence and audit

Whoever understands the model, also understands the documentation.