Ganz einfach Dokumentationen erstellen

Das Thema Dokumentationen ist oft leider ein leidiges Thema, da der Aufwand häufig sehr hoch ist und die beste Dokumentation bei der Weiterentwicklung morgen schon wieder veraltet ist. Was gibt es also für Werkzeuge, die einem helfen vernünftige Dokumente an Anwender oder gar an mehrere Zielgruppen auszuliefern?

Was zeichnet eine gute Dokumentation aus?

Das wichtigste an Dokumentationen jedweder Art sind folgende Aspekte aus verschiedensten Blickwinkeln. Denn nicht nur der Benutzer soll eine ordentliche Unterstützung und Hilfe durch die Dokumentation erfahren, auch der Verfasser sollte die Dokumentation möglichst schnell und einfach auf dem aktuellsten Stand halten können. Daher sind folgende Dinge die maßgebliche Basis für eine gute Doku:

  • Aktualität
  • Vollständigkeit
  • gute Bedienbarkeit
  • Inhaltsverzeichnis
  • Übersichtlichkeit
  • Wartbarkeit und einfache Aktualisierung
  • Zugriff für die Projektbeteiligten auf die aktuellste Fassung

Technische Umsetzung der Dokumentation

Natürlich gibt es verschiedene Möglichkeiten ein Dokument für Anwender zu erstellen. Hier mal einige Beispiele, die mir im Projektgeschäft vorkommen können:

Mit Microsoft Word und dem anschließenden Ausdruck in eine PDF-Datei

Vorteil:

  • automatische Generierung eines Inhaltsverzeichnisses

Nachteile:

  • nicht oder nur bedingt online verfügbar bzw. änderbar
  • keine Versionierung

Dokumentation als eigene WordPress-Installation

Vorteile:

  • Online-Version
  • immer pflegbar für mehrere Redakteure
  • Revisionsmanagement
  • einheitliches Erscheinungsbild und Navigationsmöglichkeit
  • Volltextsuche
  • Feedback zu Inhalten durch Kommentarfunktion möglich
  • Kategorisierung und Schlagworte zu Einteilung

Nachteil:

  • WordPress muss installiert und ggf. angepasst werden

HTML-Dokumentation mit „Documenter“

Auf der Webseite „Documenter“ hat man die Möglichkeit seine Doku in HTML-Form zu erstellen und generieren zu lassen. Ein Beispiel wie eine klickbare HTML-Dokumentation aussieht habe ich hier mal einfach zur Ansicht abgelegt.

Vorteile:

  • Corporate Design der Doku möglich
  • verschiedene vorgegeben Designs und Styles
  • einfache Generierung
  • automatische Verlinkung als Inhaltsverzeichnis
  • online verfügbar

Nachteil:

  • keine Versionierung möglich
  • gleichzeitige Pflege durch mehrere Redakteure nicht möglich
  • Speicherung durch JSON-Datei, die auch für mehrere Redakteure abgelegt werden muss

Dokumentation mit GoogleDocs

Vorteile:

  • Freigaben für verschiedene Redakteure
  • Online-Version
  • Gleichzeitige Bearbeitung der Dokumente

Nachteile:

  • Google-Konto zur Pflege ist erforderlich
  • keine automatischen Verlinkungen (Inhaltsverzeichnis o.ä.)

Fazit: Dokumentationen kann man über mehrere Wege erstellen

Es gibt verschiedene Möglichkeiten Dokumentationen zu erstellen. Ideal wäre natürlich ein System, welches automatisches dieses Dokument erstellt. Ich würde derzeit auf den Einsatz einer eigenen WordPress-Instanz setzen oder Documenter nutzen. Das „Wie?“ wird durch das „Wofür?“ und „Für wen?“ beantwortet, es gibt nicht DIE Lösung. Allerdings helfen Online-Versionen dem Support dabei z.B. Links auf Dokumente und Inhalte versenden zu können. Daher würde ich entweder auf eine Variante mit einem eigenen WordPress oder auf Documenter setzen.

Habt ihr Erfahrungen in diesem Bereich und könnt ggf. noch sinnvolle Werkzeuge zur obig genannten Liste nennen? Ich freue mich auf Eure Kommentare und Eurer Feedback.

 

Hinterlasse einen Kommentar

*

Nächster ArtikelMonitoring: Warum wurde mein WordPress gehackt?