Ein wesentlicher Teil der Arbeit ist es, nach der eigentlichen Tätigkeit noch Dokumentationen darüber zu erstellen. Sei es eine Installationsdokumentation für Kollegen oder ein Benutzerhandbuch – wer keine Dokumentation erstellt, macht sich selbst und anderen das Leben schwer.
Im einfachsten Fall reicht zur Dokumentation natürlich ein Stift und ein Notizblock aus. Da ist aber die Wiederauffindbarkeit und die Lesbarkeit ein nicht zu unterschätzender Faktor. Was muss her? Dokumentationshelfer aller Art…
Linux-Befehl: script
Mittels script lassen sich alle Ausgaben auf einer Kommandozeile in eine Datei speichern. Dies kann später zu Dokumentationszwecken weiterverarbeitet werden, und sei es als eigene Hilfestellung, um später die gleiche Prozedur nochmals durchzuführen. Weitere Informationen lassen sich auf der zugehörigen man-Page nachlesen („man script“).
Windows: Problemaufzeichnung
Der „Problem Step Recorder“, auf Deutsch Problemaufzeichnung, zeichnet automatisch Screenshots auf. Diese können dann per Mail versendet werden und eignen sich gut zur Erstellung einer Dokumentation. Auch wenn sich diese Problemaufzeichnungen nicht so leicht weiterverarbeiten lassen, man hat zum Beispiel einen Anhaltspunkt die einzelnen Schritte z.B. bei einer Installation im nachhinein wieder nachvollziehen zu können.
Diagramme mit Dia / Visio
Viele Dokumentationen profitieren von Schaubildern über den Systemaufbau oder ein Netzwerkdiagramm. Wer Microsoft Office nutzt, hat vielleicht Visio schon gekauft und kann das dazu sehr gut verwenden. Eine kostenlose Alternative (wenn auch sehr einfach gehalten) stellt dazu Dia dar. Dia ist zudem auch unter Linux verfügbar.
Wiki-Systeme
Wiki-Systeme haben verschiedene Vor- und natürlich auch Nachteile, wenn sie zur Dokumentation eingesetzt werden. So ist eine Wiki ausreichend flexibel, um ständige Änderungen an der Dokumentation zu erfassen. Zudem lässt auch die Verlinkung von Wiki-Artikeln eine wesentlich tiefere Strukturierung der Dokumentation zu, als z.B. mit einem Inhaltsverzeichnis einer schriftlichen Dokumentation möglich wäre.
Mediawiki
Mediawiki ist wohl die bekannteste Wiki-Software, da diese auch bei Wikipedia im Einsatz ist. Von Vorteil ist der geringe Installationsaufwand, es wird lediglich ein „LAMP“-Server bzw. „WAMP“ benötigt (Linux/Windows und Apache, MySQL, PHP). Zudem gibt es eine Menge an Extensions, die das Basissystem erweitern, wie z.B. Quellcode-Syntax hervorheben, automatisch PDFs aus Seiten erstellen usw.
Ein weiterer Vorteil von Mediawiki (aber auch von anderen Wiki-Systemen) ist die integrierte Versionierung von Seiten. Dadurch können Änderungen an der Dokumentation hervorragend nachvollzogen werden. Aber auch andere Wiki-Systeme wie z.B. Dokuwiki oder XWiki bieten ähnliche Features. Im Zweifelsfall muss hier verglichen werden, welches System am ehesten die eigenen Anforderungen abdeckt.
TiddlyWiki
TiddlyWiki ist eine geniale Idee, um jederzeit eine persönliche Dokumentationsmöglichkeit dabei zu haben. TiddlyWiki ist dabei das genaue Gegenteil einer kompletten Mediawiki-Installation. Es besteht lediglich aus einer HTML-Seite mit Javascript, in der alle Infos erfasst werden. Dadurch eignet sich TiddlyWiki hevorragend um z.B. auf einem USB-Stick oder in einer Dropbox immer einsatzbereit zu sein.
Versionsverwaltung
Was bei Programm-Quellcode funktioniert, kann auch bei einer Dokumentation hilfreich sein. Dokus im Textformat (entweder Klartext oder z.B. LaTeX) können in eine Versionsverwaltungsoftware (Git, Mercurial usw., ganz nach eigenem Geschmack) „eingecheckt“ werden. Dadurch sind Änderungen an der Dokumentation besser nachzuvollziehen und/oder es kann mit mehreren Kollegen gleichzeitig an Dokumenten gearbeitet werden.
Fazit
Werkzeuge zum Dokumentieren gibt es genug. Angefangen von einer einfachen Textdatei über Worddokument oder LaTeX bis hin zur Online-Dokumentation mit Versionskontrolle. Welche Werkzeuge man nun verwendet, um eine Dokumentation zu erstellen, ist letztlich eine Geschmackssache. Wichtig in meinen Augen ist dabei, dass es eine einfache Möglichkeit gibt, unterschiedliche Versionen von Dokumenten abzulegen und darauf auch zugreifen zu können. Hier bieten sich entweder textbasierte Dokumente oder Wiki-Systeme an. Gerade Online-Systemen haben den zusätzlichen Charme in Zeiten von Smartphones und mobilen Internet jederzeit griffbereit dabei zu sein. Hoffe bei den oben genannten Tools ist das ein- oder andere interessante Tool dabei…