Dokumentieren ist ein Handwerk. Wir können unsere Kreativität effizient “zu Papier” bringen, wenn wir die notwendigen Fähigkeiten besitzen. Prinzipien der Methode CARDS+ helfen uns dabei. Viele Prinzipien der Programmierer gelten auch für Autoren, in den meisten Fällen in nur leicht abgewandelter Form.

Einfach

Das Prinzip KISS hilft uns, dass wir zielgerichtet Dokumente so schreiben, dass es unsere Leser gut verstehen. “Weniger ist mehr” bedeutet oft mehr Arbeit. Einen Sachverhalt einfach zu beschreiben, auf den Punkt zu bringen, ist nicht immer leicht. Das Ergebnis hat aber einen umso höheren Wert.

Keep it simple, stupid –  Mach’ es so einfach wie möglich.
clean-code-developer

Das Prinzip KISS besagt, dass wir eine möglichst einfache Beschreibung für Inhalte im Wiki wählen sollen. Wir wollen sicherstellen, dass wir nicht an einer großen Menge an Details ersticken, die wir im Grunde nicht brauchen. Wir wollen den Blick auf die wirklich wichtigen Dinge nicht verlieren.

“Weniger ist mehr” sagt ein Sprichwort. Weniger Inhalt, auf den wir uns aber verlassen können hat mehr Wert als eine Unmenge an Dokumenten, denen wir nicht trauen.

Einfach bedeutet, dass wir eine Struktur verwenden, die es uns erlaubt, Wissen in überschaubaren Portionen nachhaltig zu beschreiben. Wir brauchen klare Regeln, die uns leiten, die uns helfen, die richtige Detailtiefe zu erreichen. Wir brauchen eine vorgegebene Struktur, die uns hilft, Wissen sinnvoll und nachvollziehbar aufzuteilen. Ähnlich wie beim Programmieren möchten wir keinen “Spaghetti-Text” in unserem Wiki haben.

Ich persönlich finde eine andere Definition des Prinzips besser.

Keep it strictly simple – Mach es konsequent einfach.

Diese Definition beinhaltet das Wort “konsequent”. Wir müssen uns immer bewusst machen, dass wir nur das beschreiben, was wir benötigen – nicht mehr und nicht weniger. Das erfordert ein hohes Mass an Disziplin bei Autoren und Lesern. Es ist für einen Autor viel schwerer, eine Information “auf den Punkt” zu bringen als einfach drauf los zu schreiben. Wir benötigen motivierte Leser, die voneinander lernen (Reviews) und sich gegenseitig helfen (Feedback).

Einmalig

Mit dem Prinzip DRY stellen wir sicher, dass wir den Überblick behalten und jede Information nur einmal erfassen. Bei kleineren Änderung muss nur eine Seite angefasst werden. Bei großen Änderungen erkennen wir schnell Abhängigkeiten. Dieses Prinzip ist vor allem für eine nachhaltige Produktdokumentation wichtig.

Don’t Repeat Yourself – Wiederhole dich nicht.
clean-code-developer

Das Prinzip DRY hat zum Ziel, jede unnötige Dopplung oder Wiederholungen von Inhalten im Wiki zu vermeiden. Werden Dokumente über einen längeren Zeitraum gepflegt, ohne das Prinzip DRY zu berücksichtigen, dann entstehen sehr leicht widersprüchliche Informationen. Dummerweise erkennen wir in den meisten Fällen nur sehr schwer oder gar nicht, welches die letzte Änderung war und vermutlich gültig ist. Das führt aber dazu, dass dem Inhalt als Ganzes misstraut wird, das Dokument “verdirbt”.

Wie beim Programmieren wird dieses Prinzip sehr häufig missachtet, weil es Kraft und Disziplin erfordert, das Prinzip in der Praxis umzusetzen. Um diese Hürde zu überwinden, benötigen wir

  1. gute Strukturen, die im Team bekannt sind,
  2. klare Regeln, um Änderungen prüfen zu können und
  3. effektive Werkzeuge, um existierende Inhalten schnell und sicher finden zu können.

Eine redundanzfreie Ablage hilft uns bei den Punkten 1 und 2. Redundanzfrei bedeutet ja auch wörtlich “frei von Redundanzen”, also frei von Duplikaten, Wiederholungen oder überflüssigen Informationen.

Das Wiki ermöglich Verlinkungen im Text mit häufig gebrauchten eindeutigen Begriffen aus unserem Glossar oder mit den Fachklassen. Informationen aus anderen Quellen werden über die Link-Sammlung eingebunden. Dadurch vermeiden wir mehrfache Erklärungen für einen häufig verwendeten Begriff.

Der Einsatz eines leistungsstarken Wiki (z.B. Confluence) wie in Punkt 3 vorgeschlagen erlaubt sehr effiziente Suchen nach Titeln oder Stichworten, um Inhalte schnell zu finden. Auch das hilft uns, schnell und sicher bereits existierende Inhalte zu finden und schützt uns davor, gleiche Informationen mehrfach zu erfassen.

Minimal

Das Prinzip COC hat die Vermeidung von duplizierten Inhalten zum Ziel. Anders als bei dem Prinzip DRY  geht es hier um Quellen außerhalb des Wiki. Insbesondere wollen wir mit dem Prinzip COC im Zusammenhang mit Produktdokumentation den Wert von Code und Unit-Tests als Dokumentation hervorheben. Das Wiki stellt dabei nur mehr eine Art Navigationshilfe für das “Lesen” von Code dar.

Convention over configuration – Konvention vor Konfiguration.
Nicholas Chen

Das Prinzip COC ist eine Ergänzung zum Prinzip DRY. Hier geht es aber nicht um die Vermeidung von duplizierten Inhalten innerhalb des Wiki, sondern von duplizieren Inhalten im Wiki aus anderen Dokumenten außerhalb des Wiki.  Als Konfiguration verstehen wir hier das Zusammenspiel von Wiki mit anderen Ablagen von Dokumenten. Dazu zählen

  • Artikel und Dokumentationen im Internet,
  • Spezifikationen, Normen und Gesetze,
  • unternehmensweite Vorgaben oder
  • rechtsverbindliche Dokumente.

Als Lösung für die Integration von anderen Dokumentenablagen bietet die Methode CARDS+ das Konzept einer Link-Sammlung.

Convention over documentation – Konvention vor Dokumentation.
ROBERT BRUCKBAUER

Das Prinzip COD ist eine Variante des Prinzips COC. Es geht im Wesentlichen um die Vermeidung von Dokumentation: Was durch Code bzw. einer code-nahe Spezifikation oder Konfiguration ausreichend gut beschrieben wird, muss im Wiki nicht mehr zusätzlich beschrieben werden. Das Wiki stellt nur mehr eine Art Navigationshilfe für Code dar.

Das Prinzip basiert auf der Konvention, dass Bezeichnungen aus dem Wiki sich direkt im Code wiederfinden, z.B. als Namensraum oder als Teil des Namens einer Klasse oder Datei.

  • Den Baustein Domain nutzen wir zur Gruppierung von Diensten. Der Titel  ist gleichzeitig Teil des Namensraums, in dem sich die Klassen der Dienste und seine öffentlich sichtbaren Informations- und Nachrichtenobjekte befinden. Auch der Name des git-Repository mit den Build-Projekten leitet sich vom Titel ab.
  • Den Baustein Service nutzen wir, um einen Dienst innerhalb des Systems einen eindeutigen Titel zu geben und seine Funktion zu beschreiben. Der Titel wird zur Bildung des Names des Dienstes verwendet, z.B. als Interface oder Hauptklasse des Dienstes.
  • Der Baustein Event bzw. Entity gibt einer Nachricht bzw. Fachklasse einen eindeutigen Titel und beschreibt seinen Inhalt.  Der Titel findet sich im Namen der Implementierungsklasse wieder. Bei der Verwendung von Schemaspezifikationen wie beispielsweise Apache Avro oder XSD ist es der Titel gleichzeitig der Name der Schemadatei . Erst dort sehen wir alle Details, z.B. Typ oder Einschränkungen (Constraints) einer fachlichen Eigenschaft.

Wenn wir diese einfach umzusetzenden Regeln berücksichtigen, dann brauchen wir keine spezielle Dokumentation mehr, um einen Dienst, eine Nachricht oder eine Fachklasse mit der technischen Lösung zu verknüpfen. Der Name allein reicht. Er ist der ideale Einstieg in die Implementierung.

Dieses Prinzip hilft auch bei der Durchsetzung der gemeinsamen Sprache im Projekt.

Nachhaltig

Ziel des Prinzip SOC ist es, die Stärken der Projektmitarbeiter zu fördern und damit die Motivation zu erhöhen. Auch die klare Trennung von Projekt- und Produktdokumentation geht auf dieses Prinzip zurück. Denn keine Methode kann eine Lösung für alle Fragen bieten.

Separation of concerns – Trennung nach Belangen.
clean-code-developer

Das Prinzip SOC spiegelt sich in der Struktur des Wiki wider. Wir wollen die fachlichen von den technischen Belangen dort trennen, wo es Sinn macht. Das Ziel ist es, bei der Arbeit im Wiki die Stärken der Projektmitarbeiter zu fördern. Das erfordert eine sinnvolle Aufteilung der Inhalte. In vielen Fällen analysieren wir den Problemraum «top down», d.h. wir erforschen das «big picture», identifizieren den Nutzen und detaillieren die daraus abgeleiteten Anforderungen. Das ist ein Prozess, den wir in der Struktur mit den Bausteinen der Produktdokumentation berücksichtigen.

Stakeholder können ihr fundamentales Wissen über die Geschäftsprozesse und die Bedürfnisse der Fachabteilungen gut einbringen, wenn die Beschreibung nicht zu detailliert sein muss, also das Abstraktionsniveau sehr hoch ist. Stakeholder arbeiten direkt und ohne Kommunikationsverluste (“Stille-Post”) im Wiki und sind dadurch auch für bestimmte Inhalte (z.B. Topic) verantwortlich. Business-Analysten können damit sicherstellen, dass sie die Probleme der Stakeholder richtig verstehen. Die Entwickler können sich einen guten Überblick verschaffen.

Business-Analysten sind sehr oft überfordert, wenn sie technische Lösungen formulieren sollen. Sie sind häufig nicht am letzten Stand, was technische Lösungen betrifft, oder es fehlt ihnen das notwendige spezielle Wissen. Das Ergebnis ist, dass die beschriebene Lösung nicht mit der tatsächlichen Umsetzung übereinstimmt, weil die Entwickler später eine bessere Lösung finden. Die Lösungsbeschreibung “verdirbt”.

Auf der anderen Seite sind Entwickler schlecht darin, die grundlegenden Probleme der Nutzer zu erkennen, weil sie häufig in Lösungen denken. Hier spielen Business-Analysten ihre Stärke aus, wenn sie sich auf diese fachlichen Probleme konzentrieren können. Und sie fühlen sich in den meisten Fällen auch wohler damit.

Effizient

Das Prinzip SLA spiegelt sich in der Struktur des Wiki wieder. Gerade bei der Beschreibung fachlicher Inhalte arbeiten sehr oft Personen zusammen, deren Fähigkeiten sehr unterschiedlich sind. Um diese Zusammenarbeit effizient zu gestalten, darf der Inhalt eines Bausteines sich in seinem Abstraktionsniveau nicht ändern.

Single level of abstraction – Ein Abstraktionsniveau.
clean-code-developer

Das Prinzip spiegelt sich in der Struktur des Wiki wieder. Für jede Seite im Wiki ist klar definiert,

  • wer die Seite vorrangig bearbeitet,
  • welche Struktur die Seite hat,
  • was in der Seite beschrieben werden soll und
  • was nicht in diese Seite gehört.

Gerade bei der Beschreibung fachlicher Inhalte arbeiten oft Personen zusammen, deren Fähigkeiten unterschiedlich sind. Um diese Zusammenarbeit effizient zu gestalten, darf der Inhalt in einem bestimmten Baustein sich in seinem Abstraktionsniveau nicht wesentlich ändern.

Zielgruppenorientiert

Anders als beim Programmieren verwenden wir das Prinzip SRP beim Dokumentieren im wörtlichen Sinn. Wir legen für jeden Baustein im Wiki fest, wer der verantwortliche Autor und die Leser sind. Die Vorgaben der Methode für die Bausteine im Wiki unterstützen den Autor, den Inhalt verständlich und passend für die Zielgruppen zu schreiben.

Single responsibility principle – Nur ein Verantwortlicher.
clean-code-developer

Das Prinzip SRP verwenden wir beim Dokumentieren anders als beim Programmieren. Wir verwenden das Prinzip im wörtlichen Sinne und legen für jeden Baustein im Wiki verantwortliche Rollen fest, die Inhalte im Wiki erstellen und pflegen.

  • Die Systembeschreibung pflegen Stakeholder, Business-Analysten  und Software-Experten.
  • Das Benutzerhandbuch pflegen die Business-Analysten oder technische Redakteure, unterstützt von ausgewählten Nutzern.
  • Das Betriebshandbuch pflegen Software-Experten und Entwickler zusammen mit den Verantwortlichen der Betriebsorganisation.
  • Die Architekturdefinition pflegen Software-Experten und Entwickler.

Innerhalb dieser großen Bereiche der Produktdokumentation werden Verantwortliche für den Inhalt jeder Seite im Wiki eindeutig bestimmt. Eine Seite im Wiki hat immer genau einen Autor, bis der Inhalt “fertig” ist – natürlich gemäß einer vom Team verabschiedeten Definition von “Fertig”.

Für die Veröffentlichung einer vollständigen Dokumentation gibt es die Rolle des Gärtners. Er ist verantwortlich für den Betrieb des Wiki, verwaltet die Nutzer, vergibt Rollen und Rechte. Als Gärtner ist er gleichzeitig Coach, hilft den Autoren bei der einheitlichen Gestaltung der Inhalte.

Transparent

Der Scrum Guide beschreibt das Prinzip der «Definition of Done» (kurz DOD) als ein Werkzeug der Transparenz. Transparenz fällt einem nicht in den Schoß, sie ist ein Weg, den es zu beschreiten gilt. Transparenz ist Arbeit. Die DOD verkörpert ein explizites und geteiltes Verständnis davon, unter welchen Bedingungen ein Produktinkrement fertig ist.

Definition of Done – Definition von Fertig.
Scrum Guide

Der Scrum Guide beschreibt das Prinzip der «Definition of Done» (kurz DOD) als ein Werkzeug der Transparenz. Transparenz fällt einem nicht in den Schoß, sie ist ein Weg, den es zu beschreiten gilt. Transparenz ist Arbeit. Die DOD verkörpert ein explizites und geteiltes Verständnis davon, unter welchen Bedingungen ein Produktinkrement fertig ist.

Im Internet gibt es eine ganze Reihe weiterer Definitionen:

The definition of done is a shared understanding of expectations that software must live up to in order to be releasable into production, managed by the development team.

Weiterlesen auf scrum.org

The definition of done is orthogonal to user acceptance criteria (functional acceptance) for a feature. It is a comprehensive checklist of necessary, value-added activities that assert the quality of a feature and not the functionality of that feature. Definition of done is informed by reality where it captures activities that can be realistically committed by the team to be completed at each level (feature, sprint, release).

Weiterlesen auf scrumalliance.org

The team agrees on, and displays prominently somewhere in the team room, a list of criteria which must be met before a product increment “often a user story” is considered “done”. Failure to meet these criteria at the end of a sprint normally implies that the work should not be counted toward that sprint’s velocity.

Weiterlesen auf agilealliance.org

The definition of done is an agreed list of criteria that the software will meet for each product backlog item. Achieving this level of completeness requires the Team to perform a list of tasks. When all tasks are completed, the item is done. Don’t confuse the definition of done with acceptance criteria, which are specific conditions an individual item has to fulfill to be accepted. The definition of done applies uniformly to all product backlog items.

Weiterlesen auf less.works

Ein Team setzt sich Ziele. Die DoD ist das Versprechen, diese Ziele erreichen zu wollen. Typischerweise enthält eine DOD mindestens Angaben zur Qualität von Code, was automatisch auch Vorgaben für den Test beinhaltet. Aber eine DOD muss alle für die Qualität relevanten Themen wie Automatisierung, Installation und Dokumentation betrachten.

Die Schlussfolgerung ist ganz einfach: Eine Produktdokumentation gehört zum Produktinkrement. Folglich ist eine Story nur dann am Ende eines Sprints fertig, wenn das Team angemessen dokumentiert hat. Mit der DOD wird definiert, was «angemessen» bedeutet. Gleichzeitig ist es das Versprechen des Teams, die Produktdokumentation zu pflegen.