Project Description

Anforderungen an Wiki-basierte technische Dokumentation

Sie kennen Wiki als Wissensdatenbank durch eigenen Einsatz oder durch Wikipedia? Wenn ein Unternehmens-Wiki wie Atlassian Confluence für technische Dokumentation eingesetzt werden soll, ergeben sich zusätzliche Fragestellungen und Anforderungen:

  • Kollaborative Content-Erstellung –  Im Gegensatz zur klassischen Knowlegde Base, die aus einzelnen Seiten von einzelnen Autoren gepflegt wird, und in der man bereitwillig sucht, arbeiten bei einer technischen Dokumentation mehrere Autoren gemeinschaftlich an einer großen, seitenübergreifenden Dokumentenbasis und man erwartet einen Lesefluss über die gesamten Inhalte. Dies bringt interessante Fragen mit sich: „Ist die Gewichtung einzelner Themenbereiche in der Gesamtdokumentation stimmig?“ oder aber „Wie erstelle und bewahre ich einen Lesepfad durch die Dokumentation als Ganzes?“
  • Redaktionelle Prozesse – Wenn viele Personen gemeinschaftlich an einer großen Sache arbeiten, bedarf es bestimmte Vorgehensweisen oder Prozesse. Im Falle einer Wiki-basierten technischen Dokumentation muss dieses „Wiki“ primäre redaktionelle Fragen adressieren. Dazu gehören die Fragen:  „Wie funktioniert der Review-Prozess einzelner Wiki-Seiten?“ und im Gegenzug auch „Wie erfolgt die Überprüfung und Freigabe von einzelnen Dokumenten bzw. der Dokumentation als Ganzes?“
  • Verwaltung verschiedener Dokumentversionen –  Technischer Dokumentation ist zu eigen, dass zu bestimmten Zeiten Versionsstände als verbindlich veröffentlicht werden, die dann auch im Nachgang in genau dieser Form reproduzierbar sein müssen. Es muss für den Confluence-Einsatz geklärt werden, wie solche Versionen technisch erzeugt werden können und wie mit diesen parallel effizient gearbeitet werden kann.
  • Wiki-Export in andere Dokument-Formate – Je nach konkreter Art der technischen Dokumentation besteht die Notwendigkeit auch „traditionelle“ Medienformate wie PDF oder eine Papierfassung bereitzustellen. Hierbei muss gewährleistet sein, dass sich sämtliche Inhalte entsprechend exportieren lassen (Wie exportiere ich ein Video?) und das etwaige Corporate Design Anforderungen fehlerfrei umsetzbar sind.

Beispiele für die Lösung „Technische Dokumentation mit Confluence“

Nicht jedes Team von Dokumentationsautoren wird von den oben geschilderten Punkten im gleichem Maße betroffen sein. Für alle diese Punkte lassen sich aber jeweils passende Lösungen finden, die aus der richtigen Mischung von organisatorischen Vorgehensweisen und Werkzeugen in Form von Confluence Plugins besteht.

[two_third last=“no“]

Die kollaborative Erstellung einer konsistenten Dokumentation kann durch einen gesamtverantwortlichen Redakteur gewährleistet werden. Dieser pflegt Seitenhierarchien, -strukturen und -vorlagen und koordiniert zudem die Dokumentationsarbeiten aller Autoren. Hierbei kann er auf Confluence eigenes Tooling zurückgreifen, wie zum Beispiel das Include und  Excerpt Include macro, welche die Copy & Paste Wiederverwendung von ständig wiederkehrenden Inhalten (Boilerplates) vermeidbar machen. Für komplexere Aufgaben wie etwa das Pflegen bestimmter Inhalte in verschiedenen Sprachen oder das komfortable verwalten eingebetteter Dateien sind zusätzliche Plugins notwendig.
[/two_third][one_third last=“yes“]


[/one_third]

[two_third last=“no“]

Redaktionsprozesse und die darin enthaltenen Arbeitsschritte können in Confluence auf verschiedene Arten umgesetzt werden. Während leichtgewichtige Ansätze mit den Confluence eigenen Labels realsiert werden können, benötigen komfortablere Varianten zusätzliche Plugins. Darunter fallen Themen wie Reviews, Freigaben und Veröffentlichungen aber auch personenbezogene Aufgabensteuerung sowie die Zustandsverwaltung von Seiten.

[/two_third]
[one_third last=“yes“]

Gängige Plugins für Redaktion:


[/one_third]

[two_third last=“no“]

Spezielle Versionstände der jeweiligen Dokumentation, zum Beispiel ein auszulieferndes Handbuch, können durch entsprechende Bereiche in Confluence, sogenannte Spaces abgebildet werden. So finden sich auch im offentlichen Atlassian-Wiki für jede veröffentlichte Confluence Version eigene Spaces, deren Namen der jeweiligen Versionsnummer entsprechen. Zudem existiert ein Space mit dem symbolischen Namen „Latest„, der die Dokumentation der aktuellsten Confluence Version beinhaltet. Diese Herangehensweise wird durch diverse Plugins unterstützt, die zum Beispiel den kompletten Space-basierten Releaseprozess in einem Schritt kapseln oder die es den Autoren erlauben, mehrere Versionsstände gleichzeitig zu pflegen und miteinander zu vergleichen.
[/two_third][one_third last=“yes“]

Gängige Plugins für die Versionierung:


[/one_third]

[two_third last=“no“]Natürlich bietet Confluence eine Export Möglichkeit der gesamten Dokumentation beziehungsweise bestimmter Teilbereiche in ein PDF-Dokument. Dieser PDF Export erlaubt einfache Anpassungen an der Titelseite sowie an den Kopf- und Fußzeilen. Durch die Verwendung von Plugins können bei Bedarf auch komplexere Layoutanpassungen vorgenommen werden. Ebenso erlauben Plugins die Verwendung dynamischer Platzhalter oder den Export in zuvor gestaltete Word Formatvorlagen.
[/two_third][one_third last=“yes“]

Gängige Plugins für Daten-Exporte:


[/one_third]

[two_third last=“no“]Aufgrund spezieller Anforderungen kann man Appetit bekommen, den Confluence Funktionsumfang noch durch weitere Plugins anzureichern. So wird man in der Softwareentwicklung häufig UML-Diagramme oder GUI-Mockups erstellen wollen und sich dementsprechend auch spezielle Unterstützung in Confluence wünschen. Wie verhalten sich aber diese Funktionen gegenüber den bisher geschilderten Anforderungen an Technische Dokumentation?

[/two_third][one_third last=“yes“]

Confluence-Plugins für Dokumentation:


[/one_third]

Info-Card

Beratung Technische Dokumentation mit Confluence

Wir können Sie bei der Einführung von Confluence und beim initialen Erstellen sowie dem Erweitern bestehender technischer Dokumentation unterstützen.

Folgendes Vorgehen hat sich hierbei in unserer Erfahrung bewährt:

  • Analyse und Bewertung der Anforderungen Ihrer technischen Dokumentationsszenarien
  • Beratung bei der Auswahl der Werkzeuge
  • Gemeinsame Erarbeitung eines Redaktionsprozesses für Dokumentationserstellung und Veröffentlichung
  • Unterstützung beim Aufbau der Confluence Strukturen (Spaces, Templates, Übersichtsseiten, usw.)
  • Ausbildung Ihrer Confluence Anwender passend zur späteren Rolle (Autor, Redakteur, Reviewer, Gärtner usw.)
  • Wir helfen Ihnen gerne beim Confluence Import von Bestandsdokumentation aus anderen Formaten wie Word.
Ihr Ansprechpartner

Dirk M. Sohn
(+49) 621 71839-42
sohn<at>oio.de (Hinweis: <at> bitte durch @ ersetzen)