Revisionssichere Dokumentation

Aufwand und Nutzen

Für Unternehmen ist die Dokumentation von Produkten und Prozessen zu einer Aufgabenstellung geworden, die nicht unerhebliche Ressourcen bindet. Einige Unternehmen erfüllen daher nur die Mindestanforderungen, die zum Beispiel an die technische Dokumentation oder die Dokumentation von Prozessen wie zum Beispiel der Qualitätssicherung gestellt werden. Doch in den meisten Fällen übersteigt der Nutzen einer ausführlichen Dokumentation den Aufwand ihrer Erstellung.

»Ohne Dokumentation keine Compliance.«

Auf die technische Dokumentation der eigenen Produkte kann ohnehin kein Unternehmen verzichten, da hier wesentliche Kundenanforderungen erfüllt werden müssen. Die Dokumentation des internen Qualitätsmanagementsystems spielt vor allem im Rahmen von Zertifizierungen nach ISO 9001 oder anderen Systemen eine zentrale Rolle. Darüber hinaus müssen auch andere Prozesse wie zum Beispiel das Umweltmanagement (ISO 14001) oder das sozial verantwortliche Handeln eines Unternehmens (ISO 26000) dokumentiert werden. Die zunehmende Abhängigkeit von IT-Systemen rückt die IT-Sicherheit in den Fokus der Unternehmensdokumentation. So ist die Dokumentation ein wesentlicher Bestandteil eines Information Security Management System (ISMS)nach ISO/IEC 27001.

Die Vorteile einer guten Dokumentation liegen auf der Hand: Ohne Dokumentation keine Transparenz und keine Compliance. Darüberhinaus dient die unternehmensinterne Dokumentation dem Wissensmanagement und bildet damit ein unverzichtbares Standbein für die künftige Unternehmensentwicklung.

Digitale Dokumentation in Wiki und CMS

Heutzutage werden Dokumentationen digital erstellt und sowohl in gedruckter als auch in digitaler Form zur Verfügung gestellt. In der Regel sind mehrere Personen an der Dokumentation beteiligt. Die konventionelle Erstellung von Dokumentationen mit Hilfe von Textverarbeitungen verliert damit an Bedeutung, da es zumeist nicht sehr sinnvoll ist, Word-Dokumente gemeinsam zu bearbeiten. Viele Unternehmen nutzen daher ein CMS wie Plone oder ein Wiki in ihrem Intranet, um Dokumentationen zu erstellen. Für den Ausdruck der Dokumentation können die Daten dann bei Bedarf in druckfähige Formate wie zum Beispiel PDF konvertiert werden.

»CMS: Bequemlichkeit mit hohem Systemaufwand«

Content-Management-Systeme bieten zahlreiche Vorteile. So kann jeder Mitarbeiter von seinem Arbeitsplatzrechner aus auf die Dokumentation zugreifen und – ein entsprechendes Zugriffsmanagement vorausgesetzt – bei Bedarf die Dokumentation editieren. So entstehende lebende Dokumente mit stets aktuellem Inhalt. Eine spezielle Software auf dem Rechner des Mitarbeiters ist bei modernen webgestützten Systemen nicht mehr erforderlich.

Der Nachteil einer solchen Lösung liegt vor allem in ihrer Komplexität. Content-Management-Systeme sind in der Regel datenbankgestützte Systeme, die gewisse Anforderungen an die Systemadministration stellen. Sie müssen installiert und gepflegt werden. Sicherheits-Updates müssen regelmäßig eingespielt werden. Und die Migration auf ein anderes System ist häufig sehr aufwändig und kostspielig. Falls im Unternehmen jedoch ein CMS vorhanden ist, bietet sich diese Lösung geradezu an.

Revisionssichere Dokumentation mit Sphinx und Git

Eine leichtgewichtige Alternative bietet die Dokumentationssoftware Sphinx in Kombination mit einer Versionsverwaltung wie Git. Sphinx ist eine Single-Source-Publishing-Lösung, die aus einfachen Textdateien diverse Ausgabeformate wie HTML und PDF erstellen kann. Sie können Ihr Qualitätshandbuch mit Sphinx als Website sowie als PDF-Dokument für den Ausdruck erstellen. Je nach Bedarf können Ihre Kunden und Mitarbeiter auf die QM-Website oder das entsprechende QM-Handbuch zugreifen.

Die Basis der Dokumentaton bilden einfache Textdateien, die mit einem Versionsverwaltungssystem wie Git versioniert werden können. Grafiken werden in Sphinx mit Hilfe einer einfachen Markup eingebunden. Git ist ein dezentrales Versionskontrollsystem, das in der IT-Industrie zur Verwaltung von Programmcode entwickelt wurde. Es ist sehr ausgereift und in seinen Grundfunktionen einfach zu bedienen. Mit Git können Sie mit einfachsten Mitteln einen revisionssicheren Dokumentationsprozess implementieren.

Wikipedia definiert Versionsverwaltung folgendermaßen:

»Eine Versionsverwaltung ist ein System, das zur Erfassung von Änderungen an Dokumenten oder Dateien verwendet wird. Alle Versionen werden in einem Archiv mit Zeitstempel und Benutzerkennung gesichert und können später wiederhergestellt werden.«

Zur Definition von Revisionssicherheit listet Wikipedia folgende Kriterien auf:

• Ordnungsmäßigkeit
• Vollständigkeit
• Sicherheit des Gesamtverfahrens
• Schutz vor Veränderung und Verfälschung
• Sicherung vor Verlust
• Nutzung nur durch Berechtigte
• Einhaltung der Aufbewahrungsfristen
• Dokumentation des Verfahrens
• Nachvollziehbarkeit
• Prüfbarkeit

Die Ordnungsmäßigkeit einer Dokumentenverwaltung ergibt sich aus ihrem Zweck. Die Regeln einer ordnungsgemäßen Dokumentation werden von diversen Normen festgelegt, von denen wir oben bereits einige erwähnt haben.

»Revisionssichere Single-Source-Lösung«

Die Vollständigkeit aller Textversionen vom ersten Entwurf bis hin zur finalen Freigabe der Dokumentation ist durch eine Versionsverwaltung ebenso gesichert wie die Archivierung von Daten, die Sphinx für die Produktion der Ausgabeformate nutzt. Damit wird auch die technische Produktion der Unterlagen in digitaler oder gedruckter Form reproduzierbar.

Ein Versionskontrollsystem bietet auch größeren Schutz vor Veränderung und Verfälschung, denn die im System gespeicherten Daten können nur mit erheblichem Aufwand nachträglich verändert oder verfälscht werden, da die gesamte Veränderungshistorie im System gespeichert ist und die Integrität der Daten durch Prüfsummen gewährleistet ist.

Sicherung vor Verlust: Daten, die von mehreren Personen in einem dezentralen Versionskontrollsystem wie Git verwaltet werden, können nicht so leicht verloren gehen, selbst dann, wenn regelmäßige Backups unterlassen werden. Denn in Git enthält jede lokale Kopie des Repositories die vollständigen Informationen des Projekts. Ein zentrales Repository kann bei einem Crash also jederzeit mit Hilfe der lokalen Kopie eines Mitarbeiters wiederhergestellt werden.

Nutzung nur durch Berechtigte: Der schreibende und lesende Zugriff auf das zentrale Repository kann auf einen bestimmten Benutzerkreis begrenzt werden. Veränderungen am Repository durch berechtigte Personen werden protokolliert, sodass jederzeit rekonstruierbar ist, wer was geändert hat. Damit ist auch die Nachvollziehbarkeit gewährleistet, denn die Versionshistorie speichert zuverlässig, wer wann welche Änderung vorgenommen hat. In Git können Versionsstände bei Bedarf mit privaten Zertifikaten (GPG/PGP) signiert werden.

Diese umfassende automatische Protokollierung aller Arbeitsschritte sowie die Möglichkeit Änderungen durch Kommentare zu erklären, erleichtert letztendlich auch die Prüfbarkeit der Daten und des Produktionsprozesses in einer Revision.

»Geringer Installations- und Betriebsaufwand«

Weitere Vorteile von Sphinx und Git sind die einfache Installation und Wartung des gesamten System. Auf Mitarbeiterrechnern muss lediglich Standardsoftware installiert werden. Eine minimale Arbeitsplatz-Installation umfasst das Versionssystem Git und einen bedienungsfreundlichen Texteditor. Das Dokumentationssystem Sphinx muss nicht notwendigerweise auf den Rechnern der Autoren installiert werden. Es reicht, wenn die Generierung der Ausgabeformate auf einem zentralen Server erfolgt. Die Online-Version der Dokumentation wird als statische Website realisiert, wofür lediglich ein einfacher Webserver notwendig ist. Alle Daten liegen in einfacher Textform bzw. als Grafik in entsprechenden Bildformaten im normalen Dateisystem vor. Eine Datenbankverwaltung entfällt ebenso wie die Pflege eines aufwändigen CMS. Bei einem Betriebssystemupgrade ist eine Migration der Daten in der Regel nicht notwendig. Beim Umzug auf neue Hardware können die Daten einfach auf den neuen Server kopiert werden.

Der Nachteil dieser Lösung liegt im Schulungsaufwand. Mitarbeiter, die als Autoren tätig sind, müssen in der Benutzung von Git und Sphinx geschult werden. Man sollte dabei von einem ein- bis zweitägigen Schulungsaufwand ausgehen.

Fazit

Unternehmen, die bereits ein CMS in Betrieb haben, sollten evaluieren, ob sie das System auch für Dokumentationszwecke einsetzen können. Häufig werden Websites mit Systemen betrieben, die als CMS tituliert werden, aber nicht immer über die notwendigen Funktionen für Dokumentationszwecke verfügen. Hier gilt es kritisch zu bleiben und sich nicht an ein System zu binden, das für andere Zwecke entwickelt wurde.

»CMS oder Sphinx? Das ist hier die Frage!«

Unternehmen, die noch kein leistungsfähiges Intranet-CMS betreiben, sollten die Sphinx-Variante prüfen. Sie ist mit geringem Aufwand zu realisieren. Der Schulungsaufwand ist nicht höher als bei einem neu eingeführten CMS. Der geringe Systemaufwand macht Sphinx+Git außerdem zu einer idealen Interimslösung. Falls sich das System in der Praxis nicht bewährt, können Sie später ohne zusätzlichen Aufwand zu einer CMS-Lösung wechseln. Umgekehrt ist der Aufwand höher.

Unternehmen, die Git oder ein vergleichbares Versionsmanagement ohnehin nutzen, sollten Sphinx in jedem Fall evalulieren. Da es sich bei Sphinx im Kern um ein System zur Software-Dokumentation handelt, fügt es sich harmonisch in die Arbeitsprozesse von Entwicklern ein. Unternehmen, die überdies eine Code-Hosting-Plattform betreiben, können mit Sphinx ihre Dokumentation ebenfalls auf dieser Plattform verwalten. Eine solche Code-Hosting-Plattform ermöglicht sogar die Bearbeitung von Texten through-the-web, was die Fehlerkorrektur durch Mitarbeiter ohne Erfahrung mit Sphinx oder Git sehr erleichtert.

Jan Ulrich Hasecke berät Sie gerne bei der Auswahl eines geeigneten Systems. Hasecke ist Autor des Buches »Software-Dokumentation mit Sphinx« und Verfasser des deutschsprachigen Benutzerhandbuches für das Enterprise-CMS Plone.

Buchempfehlung

Sphinx ist ein leistungsfähiges Werkzeug für die Dokumentation von Software. Ursprünglich geschrieben, um die Programmiersprache Python zu dokumentieren, entwickelte sich Sphinx in der Python-Community schnell zum Standard.

»ein rundum gelungenes Buch zu diesem Thema, welches sowohl eine gute Einführung bietet als auch später als Nachschlagewerk dienen kann.«

(Jochen Schnelle in ›freies Magazin‹ 11⁄2015)

Amazon Kindle iTunes Google

Buchseite