Was ist mit der Hygiene?

Was ist mit der Hygiene?

Hygiene ist der Sammelbegriff für Maßnahmen zur Erhaltung der Sauberkeit. Die Methode CARDS+ definiert solche Maßnahmen im Zusammenhang mit der Erstellung und Pflege einer Produktdokumentation.

12 Was ist mit der Hygiene

Ich habe mich in einem früheren Beitrag mit der Frage beschäftigt, was mit der Qualität von Dokumenten passiert, die wir in einer irgendwie gearteten Ablage für eine gewisse Zeit speichern und zu einem späteren Zeitpunkt wieder hervorholen. Ein Dokument verliert immer mehr Qualität, je länger es unverändert liegen bleibt, während sich das Produkt weiterentwickelt. Es verdirbt. Schlimm an verdorbenen Dokumenten ist, dass wir sie nicht als solche erkennen.

Was bedeutet aber Hygiene für eine Produktdokumentation?

Definition

Das Wort Hygiene stammt aus dem Griechischen und bedeutet „der Gesundheit dienende Kunst“.

Unter Datenhygiene verstehen wir alle Tätigkeiten, die die Reinheit von Daten sicherstellen. Daten gelten dann als rein, wenn sie fehlerfrei sind. Verdorbene Daten können durch eine Vielzahl von Faktoren verursacht werden. Dazu zählen doppelte, unvollständige oder veraltete Datensätze.

Mit dem Begriff Codehygiene fassen wir manuelle oder automatisierte Verbesserungen von Code zusammen, ohne die tatsächliche Programmfunktion zu verändern (englisch: refactoring). Sauberer Code (englisch: clean code) reduziert den Aufwand für die Wartung, ist leichter erweiterbar und als Dokumentation besser lesbar. Auch die Verwendung von Werkzeugen wie PMD, Checkstyle, Findbugs, SonarQube, Teamscale, etc. zur Überprüfung der Qualität des Codes gehört zu den Maßnahmen der Codehygiene.

Saubere Dokumente

Eine saubere Systembeschreibung in einem Wiki enthält nur gültiges Produktwissen. Unter Hygiene verstehe ich daher alle Tätigkeiten, die dazu beitragen, dieses Ziel zu erreichen. Hygiene umfasst auch alle Maßnahmen, die darauf abzielen, verdorbene Inhalte zu identifizieren und so schnell wie möglich zu korrigieren. Aber Produktwissen wächst und ändert sich in einem agilen Umfeld laufend. Wir erarbeiten es

  • in Workshops mit Stakeholdern und dem Product-Owner,
  • in Meetings des cross-funktionalen Teams und
  • während Entwicklung und Testdurchführung im Sprint.

Eine saubere Architekturdefinition enthält alle wichtigen Entscheidungen und beschreibt grob die Komponenten des Systems. Sie muss vor allem synchron mit dem Code sein, d.h. eine Beschreibung eines Service, einer Entity oder eines Events hat zumindest den gleichen Namen wie die konkrete Realisierung.

Keine Hürden

Die Hemmschwelle für Änderungen muss so gering wie möglich sein. Die Änderungen müssen aber nachvollziehbar sein.

Der Mensch an sich ist bequem, darum sind alle Arten von Hürden Gift für die Qualität der Inhalte.

  • Dokumente müssen leicht anpassbar sein.
  • Dokumente haben keinen Besitzer.
  • Die Reihenfolge von Unterseiten kann festgelegt werden.

Jeder Autor im Wiki darf gleichberechtigt Inhalte verändern. Es gibt keinen “Besitzer” für Seiten. Die Produktdokumentation ist neben Code ein sichtbares Ergebnis aller Projektmitarbeiter.

Teamwork

Wir brauchen viel Disziplin, damit wir dieses Produktwissen zeitnah, vollständig und sachlich korrekt in das Wiki übernehmen. Hilfreich sind Flipcharts oder vergleichbare Hilfsmittel, die am Ende eines Meetings konsequent abfotografiert werden. Auch Aufnahmen mit Mikrofon oder Videokamera sind hilfreich, müssen aber von allen Beteiligten akzeptiert werden. Das ist eine Kulturfrage im Team und drückt auch das Maß an Vertrauen innerhalb des Teams aus. Wichtig ist aber, dass diese Bilder oder Aufnahmen nur einen Zwischenstand darstellen. Wir müssen das darin enthaltene Produktwissen entsprechend den Regeln der Methode im Nachgang durch den Product-Owner oder einen Business-Analysten aufarbeiten. Dieses Aufarbeiten hat Vorteile:

  • Im Meeting wird lang und intensiv über ein Thema gesprochen. Das Ergebnis ist überraschend oft sehr kompakt. Und nur das Ergebnis gehört ins Wiki.
  • Bilder sagen zwar mehr als tausend Worte. Aber Bilder in Meetings entstehen während einer Diskussion. Dadurch sind Bilder am Ende meist so vollgepackt mit Details, dass der Überblick verloren geht. Beim Nacharbeiten kann der Business-Analyst die Entstehung des Bildes nachvollziehen und in Einzelschritte zerlegt ins Wiki übernehmen.
  • Die Ergebnisse von Meetings sind in den seltensten Fällen bereits so strukturiert, wie es die Methode fordert. Eine effektive Zerlegung in Topic, Epic, Case oder Layout ist darum erst möglich, wenn das Ergebnis als Ganzes feststeht.

Ganz besonders wichtig ist es, die Dokumentation für das Software-Projekt (Onbording, Projektüberblick, Projektorganisation und Team-Seiten, Protokolle, Berichte, Präsentationen) und das Software-Produkt (Systembeschreibung, Architekturdefinition, Benutzer- und Betriebshandbuch) zu trennen. Die Produktdokumentation wird im Rahmen der Methode langfristig gepflegt, während wir die Projektdokumentation nur für begrenzte Zeit brauchen. Zur Projektdokumentation zählen auch die bereits erwähnten Bilder und Aufnahmen aus Workshops und Meetings, alle Arten von Protokollen und alle Dokumente, die nicht durch die Methode definiert sind. Die Projektdokumentation existiert zwar, solange es das Projekt gibt. Aber wenn wir uns den Lebenszyklus von erfolgreichen Software-Produkten anschauen, dann existiert die Produktdokumentation wesentlich länger. Eine Vermischung dieser beiden Arten von Dokumentation führt zwangsläufig zu Problemen, weil die Ziele der Projekt- und Produktdokumentation ganz unterschiedlich sind.

Die Trennung der unterschiedlichen Arten von Dokumentation muss ganz klar sein, am besten durch unterschiedliche Bereiche im Wiki. Eine Vermischung bläht eine Dokumentation nur unnötig auf. Es gibt niemanden mehr, der die Verantwortung für so ein “multifunktionales” Wiki übernimmt. Die Autoren verlieren schnell den Überblick, die Leser werden durch den Umfang und Vielfalt der Dokumentation abgeschreckt.

Review

Einen Punkt möchte ich in diesem Zusammenhang jedoch besonders hervorheben: Reviews sind obligatorisch, auch für kleine Korrekturen. Jede Änderung einer Seite muss formal und inhaltlich geprüft werden. Nur so können wir verhindern, dass fehlerhafte Änderungen unerkannt bleiben und langsam die Inhalte verderben. Jeder Review gibt außerdem dem Autor ein frühes Feedback zu seiner Änderung. Wie jede Änderung am Code kann auch die Änderung der Dokumentation als Aufgabe im Rahmen einer User-Story in einem Sprint geplant und geschätzt werden. Dann wird der Review der Dokumentation mit dem Abschluss der User-Story durchgeführt.

Feedback

Feedback ist ganz wichtig. Wir wollen Feedback zu jeder Zeit und von allen Zielgruppen der Dokumentation.

Wir brauchen auch hier ein großes Maß an Disziplin, um das Feedback zeitnah zu verwerten. Leser können Feedback zu jeder Seite im Wiki als Kommentare abgeben. Gerade als Ausdruck der Wertschätzung sollten Autoren diese Kommentare nicht zu lange unbeantwortet lassen. Auch das Entfernen von älteren Kommentaren, die erledigt sind, ist eine empfehlenswerte Maßnahme.

Fazit

Anders als bei Codehygiene gibt es meines Wissens keine Werkzeuge, mit denen automatisiert Seiten in einem Wiki nach formalen Kriterien geprüft werden. Aus diesem Grund sind Reviews und das Vier-Augen-Prinzip bei Änderungen im Wiki so wichtig für die Qualität einer Dokumentation.

Onbording kann genutzt werden, um die Qualität der Produktdokumentation zu überprüfen. Die Fragen des neuen Mitarbeiters zum Produkt sind ein guter Hinweis auf Lücken oder unklare Formulierungen in der Dokumentation.