Principle of least surprise – Überrasche niemals den Leser.
GEOFFREY JAMES

Das Prinzip PLS ist eine goldene Regel in der Software-Ergonomie, Mensch-Computer-Interaktion und dem UX-Design. Sie lässt sich aber auch gut auf die Dokumentation mit CARDS+ übertragen. Jeder Baustein im Wiki hat genau einen Zweck, festgelegte Abschnitte und ist das Ergebnis eines bestimmten Prozesses im Projekt. Jeder Leser im Wiki weiß aus diesem Grund sehr genau, was ihn bei der Lektüre erwartet.

Eine wichtige Regel muss jeder Autor im Wiki beachten: Gibt es für eine bestimmte Information keinen geeigneten Baustein, dann gehört diese Information mit hoher Wahrscheinlichkeit gar nicht ins Wiki.

Leser erwarten keine Beschreibung im Wiki, für die es eine andere angemessene Form der Dokumentation gibt.

  • Code ist bereits eine sehr gute Dokumentation. Wir müssen im Projekt nur dafür sorgen, dass Code für viele lesbar ist. Code kann kommentiert werden. Aber wir sollten uns klar machen, dass guter Code selbsterklärend ist.
  • Beschreibungssprachen für Schnittstellen und Datenstrukturen sind sehr gut geeignet als technische Dokumentation. Sie sind lesbar.
  • Jeder einzelne Testfall ist ebenfalls eine sehr gute Dokumentation. Mit einem Unit-Test zeigen wir, was unser Code leistet. Alle anderen Testarten sind ebenfalls Teil der Dokumentation. Ein Lasttest zeigt die Leistungsfähigkeit eines Systems. Jeder Regressionstest ist der Nachweis, dass eine ganz bestimmte Funktion fehlerfrei ist.

Es spielt keine Rolle, ob wir Produktwissen aus einer XSD-Datei, einem Avro-Schema, der Swagger-UI, einem Fitnesse-Test oder einer Seite im Wiki beziehen. Es muss ganz einfach Information aus erster Hand sein.