In einem Vortrag über Herausforderungen und Ergebnisqualität der Pflege im Gesundheitswesen des 21. Jahrhundert war das Motto «Gutes tun und es gut tun». Die Autorin hat gleich zu Beginn ein paar sehr gute Fragen gestellt, die ich für die Methode CARDS+ und für die Frage der Autoren nach der Qualität einer Produktdokumentation adaptieren konnte:

  1. Wie wissen wir, dass wir es «gut tun»?
  2. Wissen alle Entwickler und Tester im Projekt, dass wir es «gut tun»?
  3. Weiß die Betriebsorganisation, dass wir es «gut tun»?
  4. Wissen die Stakeholder und Nutzer, dass wir es «gut tun»?

Die Antwort bei Punkt 1 ist noch leicht zu beantworten. Im agilen Umfeld, speziell bei Scrum, gibt es die sogenannte «prime directive»:

Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.
Norman L. Kerth

Punkt 1 ist unser Ziel und wir glauben fest daran, dass jeder sein bestes dazu tut. Schaffen wir es, alle Personengruppen als Leser unserer Produktdokumentation zu gewinnen, dann können wir jede Frage mit einem klaren Ja beantworten.

Glossar

Das Glossar bringt Ordnung in Begriffe. Die Begriffe sind das Vokabular der gemeinsamen Sprache in der Produktdokumentation. Seine konsequente Nutzung bedeutet, dass Autoren Begriffe in den Texten der Bausteine Topic, Epic oder Case durch Verlinkung mit dem Glossar verknüpfen. Autoren können ihre Texte dadurch sehr kompakt gestalten, weil sie Begriffe nicht immer wieder erklären müssen. Ein aufmerksamer Leser folgt dem Link in das Glossar und erkennt so gegebenfalls Widersprüche im Text mit dem Begriff. Doppelbedeutungen werden dadurch sichtbar.

Medien

Die Medienbibliothek schafft Ordnung in Bilder. Sie bildet einen Katalog für die Wiederverwendung von Abbildungen und Diagramme. Wenn Autoren die Medienbibliothek durchsuchen, bevor sie ein Bild neu gestalten, können sie Duplikate vermeiden. Der Katalog ist wie ein Fotobuch Inspiration für Autoren. In der Produktdokumentation entsteht eine gemeinsame Bildsprache. Gleiche Symbole haben in allen Abbildungen die selbe Bedeutung. Bei Diagrammen ist eine Legende mit Erklärungen für die Diagrammelemente im Kontext der Produktdokumentation eine große Hilfe und Bereicherung für Autoren und Leser.

Die Medienbibliothek ist auch ein großer Vorteil für die Autoren bei der Pflege der Produktdokumentation. Veränderungen an einem Bild werden sofort an allen Stellen sichtbar, wo das Bild eingebettet ist. Andere Autoren erkennen in ihren Seiten, ob das neue Bild noch zu ihrer Beschreibung passt. Leser können durch Feedback auf Widersprüche durch das geänderte Bild hinweisen. Die Wiederverwendung von Bildern ist explizit. Der Autor eines Bildes weiß, wer sein Bild verwendet. Damit kann er im Fall von wesentlichen Änderungen andere Autoren aktiv informieren.

ktip Confluence zeigt in den Seiteninformationen eine ganze Reihe von Metadaten zu jeder Seite. Dazu zählen neben dem Seitentitel und der URL (normal und kurz) die Seitenhierarchie und ein Verzeichnis für Links. Mit Hilfe der ankommenden Links kann ein Autor leicht feststellen, in welchen anderen Seiten sein Bild in der Medienbibliothek verknüpft ist.

Ohne Medienbibliothek sind Autoren gezwungen, sich viel intensiver über geplante Änderungen abstimmen. Jeder Autor muss seine Variante der Abbildung aktualisieren. Der Aufwand für die Änderung multipliziert sich so mit der Anzahl der Stellen, wo sie verwendet wird. Häufig schaffen es Autoren nicht, die Änderung annähernd zeitgleich freizugeben. Das führt zusätzlich zu Inkonsistenzen in der Dokumentation.

Story und Case

Die Verknüpfung des Bausteins Case mit einer Story im Product-Backlog hat den Vorteil, dass Entwickler und Tester automatisch Leser der Produktdokumentation sind. In Abschnitt Lösung sind sie Co-Autoren des Product-Owners. Sie geben Feedback während des Sprints und sind verantwortlich für die referenzierten Bausteine Service, Event und Entity. Die Verbindung von Product-Backlog und Dokumentation wird noch verstärkt, wenn der Titel für Case und Story gleich ist.

ktip Confluence ist ein ausgereiftes Produkt mit vielen Funktionen, die man für ein Wiki braucht. JIRA ist ein sehr leistungsstarkes Werkzeug und wird vom Hersteller als Werkzeug zur Vorgangs- und Projektverfolgung für agile Teams bezeichnet. Die beiden Produkte der australischen Firma Atlassian bilden ein sehr leistungsfähiges Paar.

Der Baustein Epic ist das Artefakt in unserer Systembeschreibung, mit dem wir Stories und Cases gleichermaßen gruppieren. Wie beim Case ergibt sich auch hier automatisch eine hohe Wiedererkennung durch den gleichen Titel. In beiden Fällen ist es für Leser sehr angenehm, in beiden Werkzeugen eine identische Struktur vorzufinden.

Fazit

Ein Eintrag im Glossar beschreibt einen Begriff und formuliert so ein gemeinsames Verständnis. Nutzt ein Autor einen Begriff anders, haben Leser die Chance, diesen Konflikt zu erkennen. Vor allem Leser, die nicht direkt mit dem Autor einer Seite zusammenarbeiten, bringen eine Perspektive ein, die gut für die Qualität ist. Die Medienbibliothek verfolgt das gleiche Ziel für gemeinsam genutzte Abbildungen. Passt eine Beschreibung im Baustein Topic, Epic oder Case nicht zur Abbildung, dann erkennen aufmerksame Leser sehr schnell Widersprüche. Zumindest werden die Leser Fragen zur Klärung an den Autor der Seite richten.

Qualität ist sichtbar, weil Begriffe, Abbildungen, Diagramme und Texte widerspruchsfrei sind und ein schlüssiges Gesamtbild ergeben. Qualität entsteht, wenn wir viele aufmerksame Leser haben. Schaffen wir es, dass Entwickler und Tester die Produktdokumentation aktiv verwenden, dann bekommen Autoren wichtiges Feedback aus erster Hand. Betrachten wir eine Story als «Versprechen zur Kommunikation im Team», dann bildet die Kombination aus Story und Case eine große Chance für die Qualität von Dokumentation, Code und Test.