Welche Dokumentationsprobleme gibt es?
1. Die Erstellung der Dokumentation ist sehr zeitaufwendig / finanziell teuer.
Das anschliessende Schreiben einer vollständigen und brauchbaren Dokumentation eines Programms ist sehr zeitaufwändig – mindestens genauso zeitaufwendig wie das Schreiben des Programms selbst.

2. Das Erstellen der Dokumentationen ist für den Softwareentwickler eine langweilige Aufgabe.

3. Die Dokumentation entspricht nicht dem Programm, wenn zusätzliche Änderungen am Programm vorgenommen wurden (z.B. voreilig bei der Inbetriebnahme) und neue Funktionen hinzugefügt wurden, die nicht mehr in der Dokumentation eingetragen wurden.
Wenn die Dokumentation bei neuen Programmänderungen nicht aktualisiert wird, kann es schnell passieren, dass eine solche Dokumentation völlig unbrauchbar wird, weil sie dem Leser Fehlinformationen liefert, aus denen sich der Leser ein falsches Urteil bilden kann, und es passiert schnell, dass niemand weiss, was in der Dokumentation eigentlich richtig ist. Eine schlechte Dokumentation ist schlimmer als keine Dokumentation.

4. Die Dokumentation enthält nicht die Informationen und Details, die wir benötigen würden, um Antworten auf die Fragen zu erhalten und ein Problem zu analysieren.

5. Die Dokumentation ist unverständlich geschrieben (sehr kurz oder sehr „professionell“) und ist für einen „normalen“ Menschen nicht verständlich.

Wie vermeiden wir Dokumentationsprobleme?
1. Verlasse den Dokumentationsprozess nicht bis zum Ende des Projekts. Dokumentiere jede laufende Projektphase – Projektauftrag, Use Cases, Anforderungen, Lösungen, Entscheidungen, Funktionsbeschreibung, Programmmodell, Testszenarien und Testergebnisse, Verbesserungsideen, …

2. Unterteile das Programm in Module.

3. Schreibe lesbaren Code.

4. Bevor ihr mit der Programmierung beginnt, findet eine Möglichkeit, die Programmdokumentation automatisch aus Programmdeklarationen, Definitionen und Kommentaren zu exportieren. Auf diese Weise müssen wir uns keine Sorgen machen, dass die Dokumentation dem Programm nicht folgt. Wir exportieren einfach nach jeder Programmänderung die entsprechende neue Dokumentation.

5. Kommentiere das Programm, was und warum das Programm tut. Überlege auch, wie du Kommentare schreibst, um den automatischen Export für die Leser nützlich zu machen.

6. Erstelle eine Visualisierung, die anschaulich zeigt, wie die Maschine gesteuert wird und was das Programm macht.

7. Schreibe ein Benutzerhandbuch für das HMI und integriere es in die Visualisierung.

8. Idealerweise werden Projekt und Programm ohne weiteren Aufwand automatisch dokumentiert.

Wird die Programmdokumentation separat erstellt, ist es praktisch unmöglich, die Dokumentation aktuell zu halten. Oft weiss ein Programmierer nicht einmal, dass er etwas ändert, das woanders dokumentiert ist.
Wenn die Dokumentation getrennt ist, werdet ihr die Abweichungen von dem Programm nicht bemerken.
Daher ist ein gut kommentierter Programmcode die beste Dokumentation. Hier merkt der Programmierer sofort, wenn der Kommentar nicht richtig beschreibt, was das Programm macht.
Ausserdem ist eine gut gestaltete Visualisierung eine tolle Dokumentation, die erklärt, wie die Dinge an einer Maschine funktionieren, und man wird schnell bemerken, wenn die Visualisierung nicht zum Programm auf der Maschine passt.