Aus eigener Erfahrung wird ein Gärtner regelmäßig mit der Frage konfrontiert, ob im Seitentitel das Präfix für den Baustein wirklich notwendig ist. Das Präfix ist in erster Linie eine Kennzeichnung, ein Stereotyp. Es zeigt an, welcher Baustein die Grundlage für diese Seite ist, welcher Aspekt in der Seite behandelt wird.

ktip Ein Stereotyp (englisch: stereotype) ist eine Erweiterung vorhandener Modellelemente in der Unified Modeling Language (UML). In der Praxis geben Stereotype vor allem die möglichen Zusammenhänge bei der Verwendung (Verwendungskontext) einer Klasse, einer Beziehung oder eines Paketes an.

Ähnlich wie bei UML-Diagrammen haben wir in einer technischen Dokumentation Modellelemente: Im Wiki sind es Seiten. Seiten bieten für alle gleiche Grundfunktionen, bestehend aus neun Überschriftenebenen, drei Absatzformaten (normal, für Code, für ein Zitat) und kombinierbaren Schriftstilen (fett, kursiv, unterstrichen, durchgestrichen).

Unterscheidbare Bausteine

Die Methode CARDS+ definiert Bausteine, die sich in Struktur und Definition des Inhaltes unterscheiden. Das Präfix ist der Name des Bausteins. Die Verwendung eines Präfix im Titel jeder Seite ist hilfreich für Leser, weil sie mit einer gewissen Erwartungshaltung den Inhalt einer Seite lesen können.

ktip Die einzige Ausnahme von dieser Regel bilden die Glossareinträge. Damit können die Begriffe aus dem Glossar ganz einfach in jedem Text verwendet werden. Ein Präfix würde hier ganz massiv stören.

Es ist ein großer Vorteil, wenn wir Leser haben, die konstruktives, zielgerichtetes Feedback geben können. Bei agiler Entwicklung legen wir entsprechend dem agilen Manifest großen Wert auf eine angemessene Dokumentation. Durch das Präfix erkennt ein Leser sofort, um welchen Baustein es sich handelt. Er kann anhand der Definition des Bausteins beurteilen, ob der Inhalt angemessen ist. Durch die bekannte Struktur des Bausteins ist er auch in der Lage, die Vollständigkeit einer Seite zu beurteilen.

Besseres Suchergebnis

Eine Produktdokumentation wird unter anderem in einem Wiki realisiert, weil es vielfältige Suchfunktionen hat. Ein Suchergebnis kann abhängig vom gesuchten Begriff viele Treffer haben, trotz der Einschränkung der Suche auf den Bereich (Space) der Produktdokumentation.

Durch das Präfix ist klar, um welchen Baustein es sich bei den Seiten im Suchergebnis handelt.

Keine Konflikte

Confluence hat die Einschränkung, dass ein Seitentitel in einem Bereich (Space) nur einmal verwendet werden kann. Das ist in vielen Fällen unkritisch. Es gibt aber eine Reihe von Bausteinen, die ohne Präfix durchaus Potential für Konflikte im Seitentitel haben.

Nehmen wir als Beispiel die Bausteine Topic und Domain. Nutzt der Product-Owner und sein Team den Modellierungsansatz “Domain Driven Design” (kurz DDD), dann passiert es sehr häufig, dass ein Topic (fachlicher Kontext) und die entsprechende Domain (technischer Kontext) den gleichen Namen haben. Jetzt könnte die Lösung sein, nur für den technischen Kontext das Präfix “Domain” zu verwenden. Ähnlich verhält es sich bei den Bausteinen Entity und Event. Mit dem Baustein Entity wollen wir ein Verständnissmodell für ein wichtiges Informationsobjekt schaffen, z.B. Zugfahrt. Gleichzeitig kann in einer event-basierten Welt so ein Informationsobjekt durch einen Event transportiert werden, z.B. die Zugfahrt mit der aktuellen Position. Es liegt also Nahe, Entity und Event den gleichen Namen zu geben. Das geht aber ohne Präfix nicht. Hier könnte die Lösung sein, nur Event als Präfix zu verwenden. Aber ist das dann noch konsequent?

Fazit

Das Präfix ist sicherlich eine Besonderheit. Das Präfix ist eine Empfehlung aus der Praxis. Sie ist sehr einfach umzusetzen. Die Methode CARDS+ funktioniert auch ohne. Aber nicht so gut. Und nachträglich das Präfix einzuführen ist Arbeit, die niemand will.