In diesem Artikel erfährst du, von welchen fünf Funktionen technische Redaktionsteams profitieren, wenn sie Docs-as-Code in GitLab nutzen.
Was ist Docs-as-Code?
Docs-as-Code oder auch Documentation-as-Code ist eine Methode zur Erstellung und Veröffentlichung von Produktdokumentationen. Dabei kommen die gleichen Tools und Prozesse wie bei der Softwareentwicklung zum Einsatz. Die Dokumentationsdateien werden zusammen mit dem Quellcode in einem Versionskontroll-Repository abgelegt.
Möchtest du wissen, ob dein Unternehmen einen Docs-as-Code-Workflow in GitLab einführen könnte? Dann lies weiter, um fünf kurze Fakten zu erfahren, wie unser Team dies umsetzt.
Funktion 1: GitLab zur Planung von Aktualisierungen der Dokumentationsinhalte
Produktmanager(innen), UX-Designer(innen), Entwickler(innen) und Qualitätssicherungs-Teams arbeiten gemeinsam daran, die Arbeit an neuen Funktionen bei GitLab zu planen und umzusetzen. Dieser kollaborative Ansatz stellt sicher, dass alle Aspekte der Produktentwicklung berücksichtigt werden und alle Beteiligten auf dem gleichen Stand sind.
Bei der Planung von Veröffentlichungen kommen in Unternehmen häufig verschiedene Tools zum Einsatz. So werden beispielsweise Kanban-Boards genutzt, um den Workflow visuell darzustellen und zu organisieren. Zusätzlich werden Issues in einem Drittanbieter-Tool erstellt und verwaltet, um Aufgaben zu verfolgen und den Fortschritt zu dokumentieren.
Bei GitLab werden Epics und Issues als nützliche Tools zur Planung der Arbeit verwendet. Epics ermöglichen, größere Projekte in kleinere Aufgaben zu unterteilen. Issues helfen dabei, spezifische Aufgaben und Anforderungen zu definieren. Issue-Boards ermöglichen die Verfolgung des Fortschritts in Echtzeit und bieten eine übersichtliche Darstellung des Projektstatus. Dabei ist Transparenz ein zentraler Aspekt dieses Prozesses. Alle Informationen, einschließlich der Diskussionen über die Planung und Umsetzung, sind für alle Teammitglieder zugänglich.
Dies fördert eine offene Kommunikation und Zusammenarbeit. Zudem haben technische Redaktionsteams so jederzeit Einblick in den aktuellen Stand der Entwicklung und können ihre Dokumentationsarbeiten entsprechend anpassen und aktualisieren. Diese Transparenz erleichtert es, Änderungen und Updates in der Dokumentation zeitnah und präzise zu integrieren.
Bei größeren Projekten werden diese in GitLab verfolgt. Änderungen werden direkt in GitLab vorgenommen und die entsprechenden Issues dort als erledigt markiert. Kommt nach einem Jahr die Frage auf, warum eine bestimmte Änderung vorgenommen wurde, ist diese genau in GitLab nachvollziehbar. Es kann problemlos geprüft werden, wer die Änderung durchgeführt hat und aus welchem Grund.
Wenn in deinem Unternehmen viele verschiedene Tools verwendet werden, stelle dir vor, wie es wäre, alles an einem Ort zu haben, anstatt beispielsweise in separaten Docs-as-Code-Tools zu arbeiten. Dies würde den Prozess schneller und effizienter gestalten. Die Zeit, die normalerweise damit verbracht wird, E-Mails, Websites und Slack zu durchsuchen, um verlorene Diskussionen zu finden, wird so eingespart. Alles Notwendige findest du in GitLab.
Für diejenigen, die ihr Wiki lieben und nicht darauf verzichten möchten, bietet GitLab auch eine Wiki-Funktion an.
Funktion 2: Feedback zu Dokumenten
Wenn du schon länger als Autor(in) arbeitest, weißt du, wie mühsam es sein kann, jemanden zu finden, der die Kapazität hat, deine Arbeit zu überprüfen.
Bei GitLab schreiben die Entwickler(innen) den ersten Entwurf der Inhalte für alle neuen Funktionen. Diese Inhalte werden im selben Repository wie ihr Code gespeichert. Die Entwickler(innen) weisen den Inhaltsentwurf den Autor(inn)en zu, die ihn daraufhin überprüfen, Vorschläge hinzufügen und ihre Ideen und Änderungen an die Entwickler(innen) zurückschicken.
Auch die Autor(inn)en öffnen Merge Requests (MRs) für inhaltliche Änderungen. Unabhängig davon, wer den MR öffnet, haben alle Teammitglieder die Möglichkeit, die Arbeit des jeweils anderen zu kommentieren.
In einem Merge Request ist es ganz einfach, die Schaltfläche „Vorschlag“ auszuwählen. Du kannst eine oder mehrere Zeilen kommentieren, Änderungen oder Bearbeitungen vorschlagen. Die Person, die den Merge Request erstellt hat, kann die Änderung direkt übernehmen oder einen alternativen Vorschlag machen, über den dann noch einmal gesprochen werden kann. Wenn du andere zur Diskussion einladen möchtest, erstellst du einfach einen neuen Kommentar und fügst dort die Namen der jeweiligen Personen ein. Sie sehen deinen Kommentar dann als Aufgabe in GitLab. Diese Vorgehensweise fördert die Transparenz und Inklusion in Teams.
Da der Inhalt des Dokuments in Markdown vorliegt, was reinem Text ähnelt, ist es einfach, die Unterschiede zwischen den Dateiversionen zu erkennen und zu sehen, wer welche Änderungen vorgenommen hat.
Vielleicht hast du schon mal in Teams gearbeitet, in denen Überprüfungen in PDFs, Word-Dokumenten oder Google-Dokumenten mit Kommentaren durchgeführt wurden. Wenn du stattdessen diesen Workflow ausprobierst, wirst du sehen, wie viel effizienter der Prozess ist. Es werden keine veralteten Versionen von Dokumenten weitergegeben, und niemand nimmt Aktualisierungen vor, die versehentlich die Kommentare eines anderen löschen.
Und wenn jemand wissen möchte, warum eine bestimmte Änderung vorgenommen wurde, kann er ganz einfach die Historie der Seite aufrufen und dort sogar sehen, wer für eine bestimmte Zeile verantwortlich ist.
Du musst keine Versionen eines PDF-Dokuments speichern und nicht mühsam versuchen, herauszufinden, wer welche Änderung vorgeschlagen hat – inGitLab wird alles ganz genau dokumentiert.
Funktion 3: Vorschau des Dokumentinhalts
GitLab bietet Tools, um den Inhalt der Dokumentseite lokal zu generieren, aber du kannst auch eine Vorschau der Dokumentseite direkt aus einem Merge Request heraus teilen. Wenn du eine Idee testen und sie jemandem zeigen möchtest, öffnest du ein Merge Request, generierst eine sogenannte „Review App“ und die geänderte Dokumentseite ist dann unter einer öffentlich zugänglichen URL verfügbar.
Deine Änderungen sind sichtbar, und du kannst sie überarbeiten oder in der aktuellen Form übertragen.
Funktion 4: Testen inhaltlicher Änderungen
Vielleicht verwendest du das Tool eines Drittanbieters, um die Links in deinen Dokumenten zu testen oder um Rechtschreib- und Grammatikregeln zu überprüfen.
Wir nutzen ebenfalls Tools von Drittanbietern (Nanoc für Links, Vale für Rechtschreibung und Grammatik), ebenso wie alles andere können auch diese Tools in GitLab und in den Arbeitsablauf der Autor(inn)en integriert werden.
Die jeweilige Autor(in) hat unsere Documentation-as-Code-Tools lokal installiert und kann alles, vom Lesemodus des Dokuments bis zu Korrekturen für Passiv- und Aktivformulierungen, auf dem lokalen Rechner einsehen. Für die Beteiligten, die nicht über diese Werkzeuge verfügen, führen wir bei jeder Übergabe eine Version unserer Tests in einer Pipeline aus. Eine Pipeline ist eine automatisierte Abfolge von Prozessen, die sicherstellt, dass der Code oder die Dokumentation korrekt getestet und validiert wird, bevor sie weitergegeben oder veröffentlicht wird.
Wenn du Entwickler(in) bist und dich nicht für eine Schreibexpert(in) hältst, kann es passieren, dass dein Merge Request aufgrund einer wichtigen Grammatik- oder Branding-Regel in der Pipeline scheitert.
Es gibt eine Liste mit vielen definierten Regeln, die verschiedene Wichtigkeitsstufen haben. Neben einem Styleguide und einer Wortliste führen wir auch Tests durch, um sicherzustellen, dass unsere Inhalte den festgelegten Regeln entsprechen.
Funktion 5: Integration von HTML-Ausgabe und Hosten des Outputs auf GitLab Pages
Bei GitLab nutzen wir die CI/CD-Pipeline dann, um die Markdown-Inhalte in HTML zu kompilieren. Anschließend werden sie auf GitLab Pages auf der Website docs.gitlab.com gehostet.
Da die Ausgabe durch eine Pipeline generiert wird, können die Dokumentseiten jederzeit aktualisiert werden. Während das Produkt einmal im Monat veröffentlicht wird, wird die Dokumentation stündlich aktualisiert. Das bedeutet, dass docs.gitlab.com immer die aktuellsten verfügbaren Inhalte enthält, manchmal sogar Informationen vor der offiziellen Veröffentlichung. Da die Planung der Entwicklung und die Implementierung in der Regel öffentlich zugänglich sind, ist die Vorankündigung von Funktionen kein Problem.
Docs-as-Code für einen besseren Workflow für technische Redakteure
Wie du siehst, bietet der Docs-as-Code-Workflow aus vielen Gründen Vorteile. Die Umstellung auf ein einziges Tool für alle Dokumentationsanforderungen kann eine Herausforderung sein, aber GitLab unterstützt den gesamten Autoren-Workflow, unabhängig davon, wer die Inhalte schreibt.
Erfahre mehr über das technische Schreiben von Docs-as-Code bei GitLab: Wenn du mehr über das Mitwirken an unserer Open-Source-Dokumentation erfahren möchtest, schau dir die Anleitung „Wie man die Dokumente aktualisiert” an.
