Dokumentationsprobleme

Artikel#: 00075

Datum: 2021-12-11

Autor: Radim

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.

© Radim-Automation, 2020–2025. Alle Rechte vorbehalten.
Die Verbreitung dieses Artikels ist mit Angabe der Quelle (Link zur Originalseite) ausdrücklich gestattet.

Verwandte vorherige Artikel:

• Visuelle Modellierung
• Wahl der Programmiersprache
• Maschinenmodularisierung
• Abkürzungen
• Modulare Softwarearchitektur
• Ein gutes Konzept = Kompletter Satz geeigneter Lösungen
• Lerne von deiner Reise!
• Warum scheitern Automatisierungsprojekte?
• Sammelt alle Anforderungen und sortiert sie!
• Funktionelles und intuitives HMI
• Verwende einen nützlichen Styleguide!
• Schreibe und akzeptiere nur lesbaren Code!
• Wer weiss es?
• Schreibe deine Best Practices und Prozesse auf!
• HMI- und SPS-Anwendungen sollen zusammenwachsen
• Speichere Email-Nachrichten im Projektordner!
• Ich sehe was, was du nicht siehst
• Mach die richtigen Dinge und mach sie richtig!
• Definiere kontinuierlich Testszenarien und Testfälle!
• Mach es nicht schlimmer!
• Schreibe ein Projekttagebuch!
• Behaltet die Antworten auf die Frage "Warum"
• Alles ist schwierig, bis es einfach wird
• Führt die Terminologie ein und vereinheitlicht sie!
• Verwirkliche jede gute Idee so schnell wie möglich!
• Komm und bleibe im "Flow"!
• Was braucht der Kunde?
• Stelle Fragen!
• Kommunikationsfähigkeiten sind äusserst wichtig
• Konzentriere dich auf das Ziel!
• Überlege auf dem Papier!
• Vermeide allzu optimistische Schätzungen!
• Schärfe deine Axt, bevor du beginnst zu fällen!
• Verstehen - Einverstanden sein - Identifiziert sein - Glauben
• Verstecke kein Problem!
• Überprüfe das Ergebnis!
• Halte es einfach!
• Verlass kein Arbeitspaket halbfertig!
• Wähle das richtige Werkzeug!
• Transparenz und Zuverlässigkeit
• Von einer Idee zu einem konsistenten System

Verwandte nächste Artikel:

• Ereignislogger als allererste im Programm implementierte Funktion
• Mein Chef war ein Held
• Versionskontrollsystem
• SPS-Netzwerkdiagramm
• Halte die Dokumentation während des gesamten Projekts auf dem neuesten Stand
• Pflege Ordnung im Programmkode
• Halte alles, was du brauchst, zusammen
• Ein unersetzbarer Mitarbeiter
• HMI - Habt einen konsistenten Stil
• Die falsche Illusion des schnellen Fortschritts

Kommentar#: 00001

Datum: 2021-12-11

Benutzer: Radim

"Wirklich lesbarer Code ist fast so einfach zu lesen wie jeder andere technische Text.
Im Gegenteil, ein unleserlicher Code, der bei jedem Lesen entziffert werden muss, passt nicht in die Dokumentation und benötigt ein weiteres ausführliches Dokument, das seine Funktion erklärt.
Die korrekte Eingabe des Codes erspart daher einiges an langweiliger Arbeit bei der Erstellung der technischen Dokumentation."
- Petr Paleta. Computer Press (2003). Co programátory ve škole neučí.

Kommentar#: 00002

Datum: 2022-10-22

Benutzer: Radim

"In der Geschäftswelt wimmelt es nur so von Dokumenten, die reine Zeitverschwendung sind. Berichte, die niemand liest, Diagramme, die keiner ansieht, und Entwürfe, die keinerlei Ähnlichkeit mit dem fertigen Produkt haben. Ihre Anfertigung dauerte unendlich lange, doch schon nach wenigen Sekunden hat man sie vergessen.
Wen Sie etwas erklären müssen, dann beleiben Sie möglichst dicht am Objekt. Anstatt zu beschreiben, wei etwas aussieht, fertigen Sie lieber eine Zeichnung an. Anstatt zu erklären, wie sich etwas anhört,summen Sie. Tun Sie alles,um Abstraktionen zu vermeiden.
Das Problem von Abstraktionen (wie Berichten und Dokumenten) besteht darin, dass sie den Anschein von Einigkeit erzeugen. Aber wenn 100 Leute das Gleiche lesen, stellen sie sich 100 verschiedene Dinge vor."
- Jason Fried, David Heinemeier Hansson. Riemann Verlag (2010). Rework. Business intelligent & einfach (Seite 105).

Kommentar#: 00003

Datum: 2022-11-03

Benutzer: Radim

"Die inhärente Komplexität der Automatisierung erfordert eine umfangreiche Dokumentation, um die Anforderungen zu definieren und die resultierenden Assets zu pflegen. Die Dokumentation ist auch sehr voneinander abhängig. Eine einfache Änderung kann sich auf mehrere Dokumente auswirken. Etwas so Einfaches wie das Ändern eines Instrumentenkennzeichens wirkt sich auf die Rohrleitungs- und Instrumentierungszeichnung, die E/A-Liste, das Gerätespezifikationsblatt, die Datenbank des verteilten Steuerungssystems (DCS), die Zeichnung des Feldanschlusskastens, die Zeichnung des Rangierverteilers und das Regelkreisblatt aus. Infolgedessen ist es schwierig, die Dokumentation während des gesamten Projekts aktuell und genau zu halten."
Übersetzt von:
- https://blog.isa.org/industrial-automation-projects-challenging-management

Kommentar#: 00004

Datum: 2023-06-16

Benutzer: Radim

"Ich sehe 5 Hauptanforderungen an die Dokumentation:

1. Mehrbenutzerfähigkeit – da viele Autoren zur Dokumentation beitragen.

2. Fähigkeit zur Versionierung – Da mehrere Benutzer an der Dokumentation arbeiten, ist es erforderlich, dass die Dokumentation mit 'Git' (oder einer anderen Versionierungssoftware) kompatibel ist. Der Grund für diese Anforderung besteht darin, dass die Dokumentation bestimmter Toolchain-Elemente (z. B. Software) mit der Version des dokumentierten Elements übereinstimmen muss, um korrekte Informationen bereitzustellen.

3. Offline-Verfügbarkeit – weil die Entwickler, die Software implementieren, nicht unbedingt Zugriff auf irgendeine Cloud haben. Sie sitzen möglicherweise irgendwo ausserhalb einer Spinnerei ohne Internet, haben aber Fragen, die eine Dokumentation erfordern. Der 'Büroentwickler' ist nicht der regelmässige Nutzer der Dokumentation, das wirkliche Leben steht mit schlechten Bedingungen im Vordergrund. Aus diesem Grund müssen einige Teile der Dokumentation zusammen mit dem auszucheckenden Code aufbewahrt werden.

4. Vollständige Übereinstimmung zwischen Software- und Dokumentationsversion – da der Entwickler nach Antworten sucht, die sich auf die Projektversion beziehen, mit der er arbeitet.

5. Allgemeine Informationen zu zugehörigen Softwareteilen sowie detaillierte Informationen zu bestimmten Funktionen, deren Verhalten und Nutzung. Daher werden extrahierte Kommentare aus dem Quellcode, wie sie von Doxygen bereitgestellt werden, höchstwahrscheinlich nicht ausreichen, da sie nicht die Gesamtinformation liefern.

Meine Schlussfolgerung:

Die Dokumentation (zumindest dieser Teil, der die Funktion eines Benutzerhandbuchs für die Entwickler hat) muss ein integrierter Bestandteil des Projekts sein und zusammen mit dem Projekt gespeichert werden – d. h. Dokumentationspaket als Teil der Entwicklungsumgebung. Damit wird die Anforderung Nr. 3 und 4 erfüllt.

Die Dokumentation muss in einer Auszeichnungssprache (HTML, XML, LaTeX etc.) verfasst sein, um sicherzustellen, dass sie von Git verarbeitet werden kann. Damit wird die Anforderung Nr. 1 und 2 erfüllt.

Eine kostengünstige und einfache Möglichkeit, an eine hochwertige Dokumentation zu gelangen, wird es nicht geben, dafür ist das Projekt viel zu komplex. Es muss Wort für Wort geschrieben werden, je früher wir beginnen, desto besser.

Entscheidend ist ein technischer Redaktor, der die gesamte Dokumentation koordiniert und dafür sorgt, dass die gesamte Dokumentation strukturiert und didaktisch wertvoll ist.

Wenn man nicht von Anfang an in eine nachhaltige und langlebige Lösung für die Dokumentation investiert, wird es in kurzer Zeit zu Wissensverlusten führen."

- Christian Vetterli
(Übersetzt aus dem englischen Original von Radim Kalousek.)

Kommentar#: 00005

Datum: 2023-07-28

Benutzer: Radim

Die Dokumentation sollte auch auf Papier ausdruckbar sein, damit sie auch ohne PC-Monitor gut lesbar ist. Daher ist es notwendig, dass das Tool/die Anwendung, in der wir die Dokumentation in elektronischer Form haben, in der Lage ist, die Dokumentation leserlich auf Standard-A4- oder A3-Papier auszudrucken, wobei die Formatierung von Text und Grafiken zu beachten ist.

Kommentar#: 00007

Datum: 2024-02-22

Benutzer: Radim

Ist Ihre Muttersprache nicht Englisch und arbeiten Sie in einem internationalen Team? Haben Sie sich im Team auf Englisch als Projektsprache geeinigt? Dann bitte:

1. Installieren und benutzen Sie alle Projektwerkzeuge auf Englisch.
2. Verwenden Sie englische Hilfedateien für die Werkzeuge.
3. Schreiben Sie englische Variablennamen und Kommentare in den Code.

Diese Regeln erleichtern die Zusammenarbeit zwischen den Teammitgliedern, die Dokumentation und die Supportaufgaben. Denn die Leute werden die gleichen Begriffe verwenden.

Sind Sie mit diesen Regeln einverstanden?
Würden Sie noch etwas hinzufügen?

Kommentar#: 00008

Datum: 2024-04-09

Benutzer: Radim

Die ordnungsgemässe Speicherung von Informationen ist für eine effiziente Arbeit und einen einfachen und schnellen Zugriff zu einem späteren Zeitpunkt von entscheidender Bedeutung.
Eine gute Archivierungsstruktur und -disziplin trägt dazu bei, Klarheit und Struktur in der Arbeitsumgebung zu erhalten, was zur Produktivität und zum Erfolg des Projekts insgesamt beiträgt.
Es ist daher wichtig, ausreichend darauf zu achten, wo und wie Informationen gespeichert werden, und geeignete Archivierungs- und Organisationsverfahren zu befolgen.