Geht das: Software-Entwickler und Technischer Redakteur arbeiten zusammen? – Docs-as-Code soll es möglich machen. Programm und Dokumentation (Handbuch) werden mit denselben Tools erstellt. So führt Dacs-as-Code mit Bausteinen wie Versionskontrolle, Markdown, also vereinfachte Auszeichnungssprache, automatische Überprüfungen und Tests zum Software-Handbuch.
Beginnt die Softwaredokumentation schon in der Entwicklung, sind Technische Redakteure früh integriert. Entwickler wiederum können neue Funktionen unmittelbar beschreiben.
Möchten Sie später lesen? Ich habe eine PDF für Sie vorbereitet:
Workflow: Software-Entwickler und Technische Redakteure schreiben Software-Handbuch
Ein Workflow für das Software-Handbuch, erstellt mit Docs-as-Code, könnte so aussehen:
Entwurf mit Markdown verfassen: Geschrieben wird in einer integrierten Entwicklungsumgebung (IDE), das heißt die Tools sind in einer grafischen Oberfläche zusammengeführt. Die Dokumentation wird in einer eigenen Versionsverwaltung (Repository) gespeichert, oder gemeinsam mit dem Code. Das Versionskontrollsystem (VCS) wiederum übernimmt die Versionierung und Organisation der Dateien. Hier geht es darum, wichtige Infos festzuhalten, ohne Schnickschnack wie Formatierung oder Illustrationen
Entwurf überprüfen: Ein Redakteur lektoriert den ersten Entwurf der Dokumentation, des Handbuchs. Er verbessert etwa Stil und Formatierung. Beide Beteiligte – Entwickler und Redakteur – können dabei leicht überprüfen, was der andere geändert hat, mit der geteilten, der Diff-Ansicht, die alte Inhalte auf der einen und neue auf der anderen Seite zeigt.
Testlauf durch Mitarbeiter: Mit einem Computercluster, das wahrscheinlich bereits vorhanden ist, kann ein Test mit Feedback von Mitarbeitern angefordert werden. Automatische Tests können ebenso eingerichtet werden. Die starten immer dann, wenn ein Pull-Request, also eine Änderungsanfrage an den Entwickler gesendet wurde.
Dokumentation, Handbuch veröffentlichen: Ist die Dokumentation okay, kann sie veröffentlicht werden. Verwiesen wird auf das Projektarchiv.
Docs-as-Code: Softwaredokumentation wird kostengünstiger und spart Zeit
Die Technische Dokumentation vereinfacht sich, wird schneller, ist automatisch immer auf dem neuesten Stand. In einer Zeit, in der ständig neue Software-Versionen erforderlich sind.
Docs-as-Code ist kostengünstig. Zum einen werden die nötigen Werkzeuge meist bereits im Haus genutzt. Auch das Wissen der Mitarbeiter kann einfließen. Vielleicht müssen zum Erstellen des Software-Handbuchs lediglich zusätzliche Lizenzen besorgt werden.
Auch Zeit wird eingespart. Eine veraltete Dokumentation, ein nicht mehr aktuelles Handbuch kann für Kunden verwirrend sein. Die Nachfragen beim Support-Team steigen. Ebenso irritiert eine ungenaue interne Dokumentation neue Teammitglieder.
Die Umstellung auf Docs-as-Code zum Verfassen eines Software-Handbuchs erfordert anfangs natürlich einen höheren Arbeitsaufwand. Vielleicht auch zusätzliche Kosten. Zudem müssen Entwickler und Redakteure sich Know-how aneignen, sich aufeinander einstellen.
Lesen Sie mehr zu Softwaredokumentation hier auf meiner Website.
Commentaires