Dokumentation UCS Architektur: Next Steps und Lesson Learned vom iterativen Schreiben

Unsere Dokumentation zur Architektur von Univention Corporate Server (UCS) ist um weitere Inhalte gewachsen und wird noch weiter wachsen. In diesem Beitrag gebe ich Ihnen einen Überblick über die neu hinzugekommenen Inhalte, stelle Ihnen eine weitere Detailebene für Administrierende und Solution Architects vor und möchte ein paar der Erfahrungen mit Ihnen teilen, die wir mit der neuen Herangehensweise der iterativen Bereitstellung neuer Dokumentation in den vergangenen Monaten gemacht haben.

Neu für Administrierende von UCS: Product Components

Der neu in die Dokumentation aufgenommene Abschnitt Product components liefert einen Überblick zu den Bestandteilen von UCS, mit denen insbesondere Administrierende interagieren. Er beschreibt kurz und übersichtlich die wichtigsten Bestandteile, Funktionen und Administrationsmöglichkeiten des UCS Portals, des UCS Managementsystems und des Univention App Centers.

Im Abschnitt Services finden Sie nun Informationen zu folgenden Themen:

1. Unterteilung des UCS Managementsystems in die Bereiche:
   • Domain Management mittels Univention Directory Manager (UDM)
   • System Management mittels Univention Management Console (UMC)
   • Configuration Management mittels Univention Configuration Registry (UCR)
2. Beschreibung des UCS Portals, seiner Unterteilung und der verwendete Technologien
3. Beschreibung des App Centers, der Arbeitsweise des Dienstes in UCS, seines Caches, seine Schnittstellen, Aktionen, Integrationen und Abhängigkeiten
4. Beschreibung des Univention App Ökosystems mit seinen beteiligten Akteuren wie z.B. App Entwickler, App Anbieter und Betreiber der Infrastruktur, den App Artefakten und der Univention App Infrastruktur

Bild 1: Aus dem Dokument: Architektur von UDM

Zur Visualisierung der Architektur nutzen wir momentan experimentell ArchiMate, ein offener Standard zur Notation und Modellierung von Enterprise Architekturen. Mit seinem Fokus auf Enterprise Architekturen ist die Notation aus meiner Sicht hervorragend geeignet, um die Architektur von UCS zu visualisieren. Als nützlicher Nebeneffekt entsteht beim Erstellen der Ansichten ein formales Modell, das weitere Analysen ermöglicht.

Bild 2: Product components in UCS, visualisiert mit der Notation ArchiMate

Durch dieses Experiment wollen wir einerseits weg kommen von Linien und Boxen mit eigener Semantik und zum anderen einen etablierten offenen Standard verwenden, der den Lesenden auch eine klare Semantik vermittelt.

Lesson learned

Seit meinem Beitrag Architekturdokumentation von UCS als Beispiel für iteratives Schreiben haben sich einige Erkenntnisse ergeben, die ich gerne teilen möchte:

1. Iteratives Schreiben funktioniert grundsätzlich gut für die Architektur von UCS. Die Inhalte sind blockweise entstanden und wurden jeweils von unterschiedlichen Experten aus dem Entwicklungsteam auf ihre fachliche Richtigkeit überprüft. Die Zuordnung bestimmter Inhalte zu Experten für die jeweiligen Themen hat sich besonders hilfreich bei der inhaltlichen Unterteilung erwiesen.
2. Das Architekturdokument ist im Textformat reStructuredText geschrieben und liegt in einem Git Repository. Mit der Software Sphinx wird daraus ein mehrseitiges HTML Dokument und ein PDF erzeugt. Des Weiteren durchläuft das Dokument noch Überprüfungen bei den verwendeten Links und der Rechtschreibung. Die dafür nötigen Schritte sind in einer sogenannten CI/CD Pipeline automatisiert. Diese Automatisierung ist für den Veröffentlichungsprozesses ein Muss, um wiederkehrende Aufwände zu sparen und reproduzierbare Ergebnisse zu erzeugen. Mir als Autor hilft die Automatisierung enorm, meinen Fokus auf den Inhalt zu halten.
3. Den agilen Ansatz haben wir bisher erst unvollständig umgesetzt. Rückblickend halte ich eine Veröffentlichung jedes der oben genannten Themenblöcke direkt nach Fertigstellung für deutlich nützlicher, weil die Inhalte damit schneller zur Verfügung stehen und bereits Kunden, Partnern und neuen Team-Mitgliedern Nutzen stiften können. Und besonders hierbei möchte ich bei der weiteren Arbeit ansetzen.

Ausblick: Fertigstellung der Product components und Services

Als Nächstes steht die Fertigstellung der Product components auf dem Plan. Es fehlt noch der Überblick zu den Berührungspunkten Command line und File and Print.

Anschließend steht der weitere inhaltliche Ausbau im Bereich Services auf dem Plan. Dazu gehören u.a. die Themen LDAP, Listener, Hooks, UDM REST API, Authentication (PAM, LDAP, Kerberos, OpenID Connect, SAML), Samba, Networking, E-Mail und Monitoring. Wenn Sie bei den Themen Präferenzen für die Priorität haben, teilen Sie mir das gerne in den Kommentaren mit.

Feedback zur Architekturdokumentation ist natürlich herzlich gerne gesehen. Nutzen Sie dafür den Feedback-Link neben jeder Überschrift. Der Link erscheint im HTML Dokument zur Architektur rechts neben einer Überschrift, wenn Sie mit dem Mauszeiger darauf zeigen. Auch hier stehe ich Ihnen für Fragen gerne zur Verfügung. Hinterlassen Sie einen Kommentar unter dem Artikel.