Überrasche niemals den Leser Principle of least astonishment— —clean-code-developer
Das Prinzip PLA ist eine goldene Regel in der Mensch-Computer-Interaktion und der Software-Entwicklung. Software sollte überraschungsarm implementiert sein. Eine Abfragemethode (engl. getter), die nicht nur einen Wert liefert, sondern gleichzeitig den Zustand der Klasse ändert, wäre überraschend und in der Regel unerwünscht.
Auf canonical.org gibt es dazu eine schöne Geschichte.
Das Prinzip PLA lässt sich aber auch gut auf die Dokumentation mit cards+ übertragen. Jeder Baustein im Wiki hat genau einen Zweck, hat festgelegte Abschnitte und ist das Ergebnis eines bestimmten Prozesses im Entwicklungsprojekt. 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 darum beachten. Für die Erfassung von Inhalten für die Produktdokumentation darf er nur die vordefinierten Bausteine verwenden. Gibt es für eine bestimmte Information keinen geeigneten Baustein, dann ist diese Information Teil der Projektdokumentation. Zu dieser Kategorie von Dokumenten gehören beispielsweise Protokolle, Zwischenberichte oder Studien. Alle Arbeitsunterlagen zur Projektorganisation (z.B. Berichte an das Management) oder zur Prozesssteuerung (z.B. das Backlog bei Scrum) gehören ebenfalls zur Projektdokumentation.
Leser erwarten eine Beschreibung im Wiki, die zum Baustein passt.
- In einem Baustein Service möchte er etwas über einen Dienst erfahren. Er möchte wissen, mit welchen Technologien der Dienst gebaut wird, welche Besonderheiten der Dienst bezüglich Verhalten beim Neustart, in der Datenhaltung oder Datenverarbeitung hat. Dazu eignen sich eine Spezifikation, die von den Entwicklern geschrieben wird und im Wiki für die Leser veröffentlicht wird.
- Die Bausteine Event und Entity repräsentieren wichtige Objekte. Die Spezifikation dazu entsteht automatisch, wenn Entwickler eine Beschreibungssprache für Datenstrukturen verwenden. Das Ergebnis ist eine Schema-Datei. Sie kann ohne weitere Bearbeitung durch die Entwickler direkt im Wiki für Leser veröffentlicht werden, weil die Schema-Datei bereits gut lesbar ist.
- In einem Baustein Case wird eine Fähigkeit der Software beschrieben. Der Regressionstest ist der Nachweis, dass alle angeforderten Fähigkeiten der Software fehlerfrei sind. Die Testfälle sind daher sehr gut geeignet, um einem Leser zu zeigen, was die Software leistet.
Zusammenfassend bedeutet das Prinzip PLA nichts anderes, als die konsequente Verwendung der Bausteine.