Die Initiative der «clean code developer» für mehr Professionalität in der Softwareentwicklung ist ein von mir persönlich geschätzter Katalog von Prinzipien und Praktiken, die uns zu professionelleren, besseren Entwicklern machen (sollen). Ich behaupte, dass sich diese und viele andere Prinzipien der Entwickler ganz leicht auch auf das Dokumentieren in einem Wiki anwenden lassen. Diese Prinzipien und ihre praktische Umsetzung sind ein wichtiger Teil der Methode CARDS+. Nur auf die bunten Bändern kann ich persönlich verzichten.

Prinzipien

Aufgrund eigener Erfahrung bin ich von der Wirksamkeit der meisten Prinzipien beim Dokumentieren überzeugt. Denn gut strukturierter Code und gut strukturierte technische Dokumentation haben vieles gemeinsam.

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.

Weiterlesen auf cardsplus.info

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.

Weiterlesen auf cardsplus.info

Das Prinzip DRY hat zum Ziel, jede unnötige Dopplung oder Wiederholungen von Inhalten im Wiki zu vermeiden.

Weiterlesen auf cardsplus.info

Das Prinzip INVEST hat seine Wurzeln im XP. Das Akronym für wichtige Eigenschaften von Anforderungen ist sehr leicht zu merken. Es sind alles Kriterien, die uns helfen, fachliches Wissen so kompakt und vollständig wie möglich zu vermitteln.

Weiterlesen auf cardsplus.info

Das Prinzip KISS besagt, dass wir eine möglichst einfache Beschreibung für Inhalte im Wiki wählen sollen. Wir müssen uns immer bewusst machen, dass wir nur das beschreiben, was wir benötigen – nicht mehr und nicht weniger.

Weiterlesen auf cardsplus.info

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 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.

Weiterlesen auf cardsplus.info

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.

Weiterlesen auf cardsplus.info

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.

Weiterlesen auf cardsplus.info

Kontinuierliche Verbesserungen

Und wie beim Programmieren gehört die Anwendung der Pfadfinderregel auch beim Dokumentieren zum Fundament professioneller Arbeit. Beim aktiven Lesen können wir bereits kleine, aber wichtigen Korrekturen durchführen. Kleine Korrekturen sind die Verbesserung von Rechtschreibfehlern oder die Verwendung von Links auf Begriffe auf das Glossar. Abhängig von der Rolle im Wiki können wir Seiten direkt ändern (Autor) oder einen Kommentar hinterlassen (nur Leser). Nach getaner Arbeit stimmt der Text also mit unserem Wertesystem mehr überein als vorher.

Gezielte Verbesserungen

Am besten noch während der Durchführung eines Reviews prüfen wir ganz gezielt die Vollständigkeit der Stichworte der untersuchten Seite. Gegebenenfalls ergänzen wir sie. Mit dieser doch recht einfachen Maßnahme kann die Suche im Wiki deutlich verbessert werden. Auch für das gezielte Korrekturlesen von neuen oder geänderten Texten bieten sich Reviews an. Vor allem mit einer guten Unterstützung der Rechtschreibprüfung durch das Wiki ist diese Aufgabe schnell erledigt. Im Sinne des Prinzips DRY kann ein Review dazu benutzt werden, Verlinkungen zu Begriffen im Glossar herzustellen. Durch diese ebenfalls recht einfache Maßnahme erkennen wir automatisch Wiederholungen im Text, die wir dann ohne Informationsverlust entfernen können.