Die Entwicklung der Produktdokumentation bei Univention am Beispiel von Nubus für Kubernetes

Seit der Ankündigung von Nubus auf dem Univention Summit im Januar 2024 hat Univention viel Arbeit in die Erstellung der begleitenden Dokumentation investiert. Dieser Blogbeitrag gibt einen Einblick, wie sich die Produktdokumentation bei Univention im Allgemeinen entwickelt und welche Prinzipien Univention bei Nubus im Besonderen angewendet hat.
Der Beitrag richtet sich an Leser, die sich für den Wert der Dokumentation von Softwareprodukten interessieren. Und es ist für diejenigen, die sich für das technische Schreiben begeistern.

Nubus für Kubernetes ist das neueste Mitglied der Univention-Produktfamilie. Es fügt sich gut in die Familientradition ein, da es ein komplexes Produkt ist, das aus vielen Teilen besteht. Es läuft auf Kubernetes, einem Open Source System zur Automatisierung der Bereitstellung, Skalierung und Verwaltung von containerisierten Anwendungen. Nubus integriert eine Vielzahl von Open Source Software, um Identitäts- und Zugriffsmanagement, eine grafische Verwaltungsoberfläche, ein Portal und vieles mehr bereitzustellen.
In den letzten zwölf Monaten hat das Nubus-Team hart daran gearbeitet, Nubus für Kubernetes öffentlich verfügbar und lauffähig zu machen. Als technischer Redakteur, der den größten Teil der Dokumentation verfasst hat, stand Nubus im Mittelpunkt meiner Aufmerksamkeit.

Die Dokumentation ist ein integraler und wichtiger Bestandteil eines komplexen Produkts. Sie ermöglicht Menschen, ein Produkt in ihrem eigenen Tempo und mit ihrer eigenen Intensität kennenzulernen. Sie können unverbindlich prüfen, ob das Produkt den Anforderungen ihres Unternehmens entspricht, und in einem persönlichen Gespräch alle offenen Fragen klären. Dies hilft dem Anbieter, das Support-Team zu entlasten und zu skalieren, da er nicht immer wieder dieselben Dinge in Einzelgesprächen erklären muss. Ohne Dokumentation ist es schwer, überhaupt anzufangen.

Für mich als technischer Redakteur ist die Produktdokumentation eine Frage des Respekts und der Wertschätzung für die Menschen, die ein Softwareprodukt nutzen. Die Dokumentation ist Teil des Produktlebenszyklus. Sie ist Teil der „Definition of Done“ in der agilen Softwareentwicklung. Sie ist die historische Aufzeichnung über die Existenz von Funktionen und Anwendungsfällen. Mit dieser Perspektive im Hinterkopf wird das Mantra „Docs, or it didn’t happen.“ der weltweiten Write the Docs-Community von technischen Autoren Wirklichkeit.

Für Univention hat Nubus die Gelegenheit geboten, die Produktdokumentation von Grund auf neu zu gestalten. In den folgenden Abschnitten möchte ich einige Grundsätze erläutern.

Umfang

Die folgenden Fragen und ihre Antworten definieren den Umfang von Dokumentation:

• Wer ist der Leser?
• Was will oder braucht der Leser?
• Was weiß der Leser?
• Welche Informationen gehören in das Dokument? Und welche nicht?
• Wo befindet sich das veröffentlichte Dokument?
• Wer ist für die Pflege des Dokuments verantwortlich?

Klare Antworten auf diese Fragen zu haben, ist für jeden, der an einem Dokumentationsprojekt beteiligt ist, sehr hilfreich. Es ist auch besonders wichtig, sich an sie zu erinnern, wenn man über zusätzliche Inhalte spricht und diese im Laufe der Zeit plant. Der Umfang hilft bei der Entscheidung über den Detaillierungsgrad des Inhalts bzw. darüber, wo geplante Inhalte tatsächlich hingehören.

Ohne einen klaren Umfang und ein klares Zielpublikum wirkt der Inhalt schwammig, oder der Detaillierungsgrad springt von niedrig zu hoch, um nur einige Beispiele zu nennen.

Agile Entwicklung

Als Softwareunternehmen verwendet Univention agile Softwareentwicklungsmethoden, um die Software schrittweise zu entwickeln. Die agile Softwareentwicklung wirkt sich auch auf die Art und Weise aus, wie technische Autoren Dokumentation erstellen. Genauso wenig wie Software als vollendet betrachtet werden kann, trifft dies auch für ihre Dokumentation zu.

Univention veröffentlicht Dokumentationsinhalte, wenn Teile, die logisch zusammengehören, wie z.B. ein Abschnitt oder ein neues Kapitel, fertig sind, nicht wenn die gesamte Dokumentation fertig ist. Interessierte können sich bereits mit dem Produkt oder seiner Architektur vertraut machen und ihre Gedankengänge fortsetzen. Die Produktdokumentation von Univention folgt dem Prinzip „release early, release often“, einer Softwareentwicklungsphilosophie mit dem Schwerpunkt auf häufigen Veröffentlichungen, um eine enge Feedbackschleife zwischen dem Ersteller der Inhalte und dem Verbraucher zu schaffen.

Dokumentation als Code

Eine Voraussetzung für agile Entwicklung ist die Prozessautomatisierung. Für die Dokumentation bedeutet dies die Anwendung von Docs as Code, einer Philosophie, bei der es darum geht, die Dokumentation mit denselben Werkzeugen zu schreiben wie den Softwarecode:

• Für die Planung verwendet Univention Epics und Issues.
• Ein Texteditor für die Erstellung von Inhalten, die in einer vereinfachten Auszeichnungssprache geschrieben sind.
• Git zum Übertragen von Änderungen in ein Quellcode-Repository.

Die Automatisierung in CI/CD-Pipelines konvertiert die Inhalte für die Zielformate wie HTML und PDF. Außerdem bietet sie Qualitätssicherungsmaßnahmen wie Rechtschreibprüfung und Link-Validierung. Technische Autoren können sich auf automatisierte Prozesse verlassen, damit sie sich auf den Inhalt konzentrieren können.

Bei der Überprüfung von Inhalten helfen Feature-Branches und Merge Requests, die Kommunikationseffizienz zu steigern. Ähnlich wie bei der Softwareentwicklung werden Inhalte in so genannten Feature Branches im Quellcode-Repository abgelegt. Bei den Inhalten kann es sich um ein neues Kapitel oder um eine Änderung an bestehenden Inhalten handeln. Ein Merge Request enthält alle notwendigen Informationen zu einer Änderung, wie z. B. eine Zusammenfassung der Änderung, die Commits, aus denen die Änderung besteht, Details zu den Änderungen und wer die Änderung an welchen Dateien vorgenommen hat. Während des Review-Prozesses sehen die Reviewer den Inhalt in ihrem Webbrowser. Sie können Kommentare zu Sätzen oder Abschnitten abgeben oder Änderungen vorschlagen. Ein Merge Request ist das zentrale Element, das die gesamte Kommunikation über eine Inhaltsänderung zusammenhält. Er erhöht die Kommunikationseffizienz, da es nur einen einzigen Kontaktpunkt gibt und Medienbrüche vermieden werden. Vorbei sind die Zeiten, in denen Autoren und Reviewer ihr Feedback zu Inhalten per E-Mail mit Anhängen austauschten.

Enger Kontakt mit Fachleuten

Der enge Kontakt zu Fachexperten ist ein Prinzip, das Technischen Autoren bei der Arbeit unterstützt. Technische Autoren brauchen direkten und regelmäßigen Kontakt zu Personen im Unternehmen, die sich mit einem Thema gut genug auskennen, um darauf aufbauend Produktdokumentation erstellen zu können. Um qualitativ hochwertige Inhalte zu erstellen, muss ein Technischer Autor ein Thema verstehen. Verstehen bedeutet, die richtigen Fragen an die richtigen Personen zu stellen.

Bei Univention nimmt der technische Autor während der Dauer eines Dokumentationsprojekts an den täglichen Teambesprechungen teil, um Fragen zu stellen, Antworten zu erhalten und weiter an den Inhalten zu arbeiten. Interviews mit Fachexperten sind ein effizienter Weg, um Rechercheergebnisse zu überprüfen und Fachwissen hinzuzufügen, ohne dass der Experte zu viel Zeit investieren muss. Die Fachexperten sind auch Teil des Qualitätssicherungsprozesses, um sicherzustellen, dass Inhalte technisch korrekt sind.

Standardisierte Notation zur Visualisierung

Die Architekturbeschreibung von Nubus für Kubernetes verwendet eine Vielzahl von Visualisierungen, um dem Leser beim Verstehen und Nachvollziehen zu unterstützen. Univention hat sich für die Unternehmensarchitektur Notation ArchiMate entschieden, da diese für den angestrebten Abstraktionsgrad die richtige Lösung bietet. Der Vorteil gegenüber der Verwendung von Linien und Kästchen ist die klar definierte Semantik für jedes Konzept in der Notationssprache. Ein technischer Autor kann sich darauf konzentrieren, die Bedeutung des Bildes zu beschreiben, ohne sich in die Semantik zu vertiefen. Für Leser, die tiefer einsteigen wollen, reicht ein Verweis auf die Spezifikation.

Beispiel für die Visualisierung im Nubus für Kubernetes Architekturhandbuch

Ich persönlich mag die Fähigkeit von ArchiMate, natürliche Sprache zu visualisieren, und die Art und Weise, wie es mir hilft, tief über ein Thema nachzudenken. ArchiMate deckt sehr gut das Schema ab, wer was mit wem macht. Es hilft auch bei Gesprächen mit Fachleuten, da der aktiv handelnde Teil in Software nicht immer offensichtlich ist.

Styleguide

Ein Styleguide ist ein Hilfsmittel, um die Konsistenz Ihrer gesamten Produktdokumentation zu gewährleisten. Er beschreibt die allgemeinen Grundsätze der Produktdokumentation, z. B. Sprache und Tonfall, Zugänglichkeit, Zielgruppe oder den Umgang mit zeitlich begrenzten Aussagen sowie bereits getroffene Entscheidungen, z. B. wie ein Begriff zu schreiben ist: „boot-loader“ oder „bootloader“. Beide Begriffe sind im Englischen korrekt, wenn Sie sie in einem Wörterbuch nachschlagen. Im Internet finden Sie verschiedene Styleguides, auch unter einer Creative-Commons-Lizenz.

In Verbindung mit einem Prosa-Linter, wie z. B. vale, entfaltet der Styleguide sein volles Potenzial, um Verstöße im Inhalt aufzudecken. Mit dem in den Texteditor integrierten Prosa-Linter sieht der technische Autor die Styleguide-Verstöße direkt im Inhalt während des Schreibprozesses. Linter sind Software-Tools zur statischen Code-Analyse. Software-Ingenieure überprüfen ihren Software-Code, um Programmierfehler, Bugs, Stilfehler und verdächtige Konstrukte zu erkennen. Prosa-Linter arbeiten ähnlich, allerdings mit Text.

Die Nubus-Produktdokumentation umfasst eine ganze Reihe von Inhalten. Sie richtet sich an verschiedene Zielgruppen, wie Betreiber, DevOps-Ingenieure, Support- und Software-Ingenieure. Sie bietet verschiedene Perspektiven, um den Aufbau des Produkts und seine Verwendung zu erklären.

Verfügbare Nubus für Kubernetes Dokumentation

Sie finden alle veröffentlichten Dokumente im Bereich Univention Nubus auf der Univention Produktdokumentationsseite.

• Das Architekturhandbuch beschreibt die Teile und deren Aufbau in Nubus für Kubernetes. Es richtet sich an Architekten, Support- und DevOps-Ingenieure.
• Das Betriebshandbuch beschreibt, wie Nubus für Kubernetes zu betreiben ist. Es richtet sich an DevOps-Ingenieure und Betreiber.
• Das Handbuch zur Anpassung und Modifikation beschreibt, wie man Nubus anpasst und erweitert. Es richtet sich an Softwareentwickler und DevOps-Ingenieure.
• In den Release Notes werden die Änderungen an jeder Version von Nubus für Kubernetes beschrieben. Sie richten sich an DevOps-Ingenieure und Betreiber.

Im Allgemeinen können Sie auf der Dokumentationsseite zu dem benötigten Dokument navigieren oder die integrierte Suche über alle Dokumente hinweg nutzen.

Allerdings ist noch nicht alles, was geplant war, verfügbar. Der Fokus liegt auf den Betreibern und DevOps-Ingenieuren, die Nubus für Kubernetes in ihrem Cluster Laufen lassen wollen. Da sich Nubus mit jeder Version weiterentwickelt, erhält die Dokumentation Inhalte, die die jeweiligen Anwendungsfälle beschreiben. Gleichzeitig enthält die Dokumentation Inhalte, die sich an die Zielgruppe der Software-Ingenieure richten, die ihre Lösungen durch Anpassung und Erweiterung von Nubus anbinden wollen.

Zum Abschluss der evolutionären Reise durch die Produktdokumentation in den letzten zwölf Monaten hier die Zusammenfassung einiger Erkenntnisse:

1. Konzentrieren Sie sich auf den Leser. Ihr Leser möchte sein Informationsbedürfnis befriedigen. Als technischer Autor ist es Ihre Aufgabe, die Dokumentation bereitzustellen, die der Leser benötigt, um seine Aufgaben mit Ihrem Produkt zu erledigen.
2. Nutzen Sie Automatisierung für sich wiederholende Aufgaben zur Erstellung der Endformate Ihrer Dokumentation oder zur Veröffentlichung der Inhalte.
3. Erstellen und verwenden Sie einen Style Guide für die Dokumentation und halten Sie sich daran. Verwenden Sie Prosa-Linter, die Ihnen bei der Anwendung der Regeln helfen.
4. Verwenden Sie eine standardisierte Notation für die Visualisierung.
5. Lernen Sie Ihren Texteditor kennen und beherrschen Sie ihn gut. Das steigert Ihre Effizienz.

Technische Dokumentation ist ein interdisziplinäres Thema. Bei Univention ist es ein großer Vorteil, dass es eine spezielle Rolle gibt, die ausschließlich für die Produktdokumentation zuständig ist. Die Rolle konzentriert sich nur auf die Dokumentation. Und die Entwicklungsteams wissen, dass diese Rolle sich um die Produktdokumentation kümmert. Das macht den Kopf frei und hilft ihnen, sich auf die Softwareentwicklung zu konzentrieren. Das bedeutet jedoch nicht, dass Softwareentwickler nicht zur Dokumentation beitragen können oder wollen.