Ein Wiki egal welchen Herstellers ist immer nur für einen gewissen Teil der Dokumentation geeignet. Selbst unsere Produktdokumentation befindet zur Vermeidung von Redundanzen nicht nur im Wiki.

  • Vertragsrelevante Unterlagen müssen in einem revisionssicheren Dokumentenverwaltungssystem gespeichert werden.
  • Schnittstellenspezifikationen werden von Partnersystemen zur Verfügung gestellt.
  • Unternehmensweite Richtlinien und Vorgaben befindet sich im Intranet.
  • Tutorials und API-Dokumentation befinden sich im Internet.
  • Unterlagen zur Code-Generierung (z.B. ein Meldungskatalog) befinden sich in einem Repositiory.

Eine Link-Sammlung ist immer dann notwendig, wenn eine Produktdokumentation in verschiedenen Versionen inkrementell gepflegt wird (also mindestens die Systembeschreibung der Version in Produktion und die aktuelle Version) und wenn es Dokumente außerhalb des Wiki gibt (z.B. API-Dokumentationen als Teil der Architekturdefinition). Beide Annahmen treffen in der Regel zu.

ktip Für Confluence gibt die Erweiterung (Add-onScroll-Version, mit dem ein ganzer Bereich (Space) versioniert wird.

Motivation

In allen Fällen wollen wir die Dokumente nicht als Kopie in unser Wiki übernehmen. Aber wir wollen sicher auf diese Unterlagen zugreifen. Sicher bedeutet in diesem Fall aber, dass es mehr als einen Link (URL) auf ein Dokument gibt. Der konkrete Link unterscheidet sich abhängig von der Version der Systembeschreibung.

In einem technisch motivierten Text (z.B. eine Decision) möchte ich das JDK erwähnen. Im Text ist es egal, ob es Java5, 6 oder 7 ist. Wenn ich jedoch auf den Link klicke, will ich auf die richtige Seite gelenkt werden, die zu der Version der Systembeschreibung passt

Es gibt noch eine ganze Reihe weiterer Beispiele aus den eingangs aufgezählten Bereichen!

Versionierung

Die Lösung dafür ist eine versionierbare Sammlung mit Seiten vom Typ Link für unser Wiki. Die Grundidee ist, dass ein Link eine Seite im Wiki ist. Der Seitentitel ist der Bezeichner des Links, der Seiteninhalt enthält die URL und eine von der Quelle abhängige Beschreibung.

URL: http://docs.oracle.com/javase/6/docs/api/
Beschreibung: Java™ Platform, Standard Edition 6
API Specification

Die erste Seitenversion bekommt den Titel “JDK” und ist in dieser Form gültig für die Systembeschreibung von Release 1. In Release 2 aktualisieren wir die Software und verwenden Java 7. Zur Dokumentation erstellen wir eine neue Seitenversion für Release 2 und ändern den Link.

URL: http://docs.oracle.com/javase/7/docs/api/
Beschreibung: Java™ Platform, Standard Edition 7
API Specification

Der Effekt ist, dass in allen Seiten ein Klick auf einen beliebigen Link zur Seite “JDK” abhängig vom gewählten Release entweder die Web-Seite für Java6 (Release 1) oder auf Java7 (Release 2) aufruft.

Fazit

Die Link-Sammlung können wir nun verwenden, um extern verwaltete Dokumente und Unterlagen mit einem von uns gewählten Namen in unserer Systembeschreibung zu verwenden. Wir sind durch die Link-Seiten unabhängig von der Strategie der Versionierung in den externe Quellen. Denn externe Quellen haben oft eine andere, häufig inkompatible Strategie zur Versionierung der Dokumente und Unterlagen.

  • Dokumentenmanagementsysteme verwenden Konzepte wie Fassungen, mehrere Dateien mit einem Prefix oder Suffix oder ganz einfach unterschiedliche Ordner.
  • Versionsverwaltungssysteme (z.B. git oder svn) strukturieren die Inhalte nach Tags, Branches oder Revisions.
  • Quellen im Intranet und Internet können nur als simple URL verwaltet werden, verbunden mit der Hoffnung, dass die URL auch lange genug gültig ist.

Selbst Unterlagen aus Papier können auf diese Art in das Wiki integriert werden, z.B. mit den Koordinaten in das Papierarchiv (z.B. Schrank, Ordner oder Lade).