Topologie & Komponenten

Zusammenfassung

Auf dieser Seite erhalten Sie einen Überblick über die Topologie rund um die Veröffentlichung der Dokumentationswebsite und lernen die wichtigsten Komponenten (openCode, GitLab CI, Docusaurus, Hosting) kennen. Die Infografik am Anfang zeigt den Flow vom Repository bis zur veröffentlichten Website.

Hier zunächst eine Infografik, welche einen Überblick über die Topologie vermittelt:

Erklärtext zur Infografik

Die Infografik zeigt den Weg vom Quelltext bis zur veröffentlichten Dokumentationswebsite (von links nach rechts):

1. openCode / GitLab: Hier liegt das Repository mit der Dokumentation (Markdown-Dateien, Konfiguration, Bilder)
2. GitLab CI: Eine Pipeline startet automatisch (z. B. bei Commits oder Merge Requests) und führt Build- und Prüf-Schritte aus
3. Docusaurus: Docusaurus erzeugt daraus eine statische Website (HTML, CSS, JavaScript) inklusive Navigation und Suchindex
4. docs.fitko.de: Das Ergebnis wird als Website bereitgestellt, sodass Nutzer:innen die Dokumentation im Browser lesen können

Das ist Ihnen alles zu technisch? Kein Problem: Nachfolgend die hoffentlich auch für Nicht-Entwickler verständliche Beschreibung der einzelnen Komponenten und ihrer Funktion.

openCode: Die Plattform

ist die zentrale Open-Source-Plattform der deutschen öffentlichen Verwaltung. Sie bildet das Fundament unserer Zusammenarbeit und ermöglicht:

• Gemeinsame Entwicklung von Software für Behörden.
• Freie Nachnutzung von Lösungen (z. B. für das Onlinezugangsgesetz).
• Transparenz und Sicherheit durch offene Standards.
• Kosteneinsparungen durch Vermeidung von Doppelentwicklungen.

Die Plattform ist ein wichtiger Baustein für die Digitalisierung der Verwaltung und trägt zur digitalen Souveränität Deutschlands bei.
openCode enthält eine GitLab-Instanz, die Ihnen unter gitlab.opencode.de (öffnet in neuem Tab) zur Verfügung steht. GitLab ist nicht nur für Programmcode, sondern auch für Dokumentationen sehr gut geeignet. Daher nutzen wir diese als technische Basis für die Erstellung von Dokumentationswebsites im Zusammenhang mit dem Föderalen Entwicklungsportal.

1. Der Zugang: Ihr openCode-Benutzerkonto

Bevor wir in die inhaltliche Arbeit einsteigen, benötigen Sie Zugang.

Wichtiger Hinweis

Ohne ein openCode-Benutzerkonto kann gitlab.opencode.de ausschließlich lesend genutzt werden.

Um Änderungen vorzuschlagen, benötigen Sie Schreibrechte auf das betreffende Repository.

Stellen Sie sich vor, Sie stehen vor dem Bürogebäude "openCode" und möchten in Ihren Raum "Mein-Dokumentationsprojekt". Dafür benötigen Sie zuerst einen Schlüssel, also Ihr openCode-Benutzerkonto, und anschließend eine Einladung in den Raum, in dem die Dokumente Ihres Dokumentationsprojekts liegen.

openCode-Benutzerkonto jetzt erstellen (öffnet in neuem Tab)

Ausführliche Informationen rund um das Registrieren und Anmelden in openCode finden Sie im openCode Guide (öffnet in neuem Tab).

Nachdem Sie Ihr openCode-Benutzerkonto erstellt haben, melden Sie sich im nächsten Schritt auf gitlab.opencode.de (öffnet in neuem Tab) an. Das ist zwingend erforderlich, da Ihr Benutzerkonto sonst in GitLab nicht sichtbar ist.
Ihr Benutzerkonto kann ohne einmalige Anmeldung in GitLab keinem Projekt hinzugefügt werden!

2. Die Berechtigung: Dem Projekt beitreten

Der Besitz eines Schlüssels (Account) allein reicht nicht – er öffnet Ihnen nur die Eingangstür zum Bürogebäude. Damit Sie im richtigen Raum (Projekt) arbeiten können, brauchen Sie zusätzlich eine Einladung. Wenden Sie sich dazu an den Product Owner oder eine technisch verantwortliche Person des jeweiligen Projekts. Diese Person fügt Ihren Account als Mitglied mit Schreibrechten (Developer oder Maintainer) zum Projekt hinzu.

GitLab und das Repository: Der digitale Aktenschrank

GitLab ist eine umfassende Plattform für die Zusammenarbeit an Software und Dokumentationen. Im Zentrum steht dabei das Repository.

Stellen Sie sich das Repository wie einen großen, gut organisierten Aktenschrank vor. Hier liegt das "Original": Alle Dokumente, Bilder und Dateien, die Bestandteil der Dokumentation sind, werden hier zentral und sicher aufbewahrt.

Information

Das GitLab Repository ist die "Single Source of Truth". Was hier im Hauptzweig (Main Branch) liegt, ist der aktuelle, gültige Stand der Dokumentation.

GitLab basiert technisch auf Git, einer Software zur Versionsverwaltung. Das bedeutet: Der Aktenschrank führt automatisch Buch darüber, wer wann welche Akte herausgenommen, geändert und zurückgelegt hat. Das ermöglicht:

• Versionskontrolle (Lückenloses Protokoll aller Änderungen)
• Teamarbeit (Gleichzeitiges Arbeiten ohne dass Akten verloren gehen)
• Automatisierung (Automatische Prüfung und Veröffentlichung)

Die Werkzeuge: Wie wir arbeiten

Um in diesem Aktenschrank zu arbeiten, nutzen wir Konzepte, die sich leicht mit der Büroarbeit vergleichen lassen.

Web IDE: Ihr Arbeitsplatz direkt im Archiv

Für die Bearbeitung unserer Dokumentation nutzen wir standardmäßig die Web IDE (Integrated Development Environment).

Analogie: Anstatt die Akten mühsam in Ihr eigenes Büro (auf Ihren lokalen Computer) zu transportieren, nutzen Sie einen voll ausgestatteten Besucher-Arbeitsplatz, der direkt im Archivraum für Sie bereitsteht.

• Dort liegen Stift, Papier und Werkzeuge bereits fertig eingerichtet bereit.
• Sie müssen nichts installieren oder konfigurieren ("Rüstzeit" entfällt).
• Sie nehmen den Ordner aus dem Schrank, setzen sich an diesen Arbeitsplatz und erledigen dort Ihre gesamte Schreibarbeit – egal ob es nur ein Tippfehler ist oder ein komplett neues Kapitel.
• Da Sie direkt an der Quelle arbeiten, sparen Sie sich den Transportweg und arbeiten immer in der korrekten Umgebung.

Branch: Die Arbeitskopie

Im Aktenschrank liegt das wichtige Originaldokument (der "Main"-Branch). Niemand darf einfach so im Original herumkritzeln – das würde zu Chaos führen.

Wenn Sie eine Änderung vornehmen wollen:

1. Gehen Sie (virtuell) zum Kopierer.
2. Machen Sie eine Kopie des Ordners.
3. Nehmen Sie diese Kopie mit an Ihren Arbeitsplatz in der Web IDE.

Diese isolierte Kopie ist Ihr Branch. Dort können Sie Seiten herausreißen, neu schreiben oder experimentieren – das Original im Aktenschrank bleibt davon völlig unberührt und sicher, bis Sie fertig sind.

Commit: Das Abheften einer Änderung

Sie arbeiten an Ihrer Kopie (Branch). Sie haben gerade Seite 3 überarbeitet. Damit dieser Arbeitsschritt nicht verloren geht, lochen Sie die Seite, heften sie fest in Ihren Ordner und kleben ein Post-it darauf.

Auf dem Post-it steht: "Rechtschreibfehler auf Seite 3 korrigiert".

• Dieser Vorgang – das feste Abheften mit der Notiz, was gemacht wurde – ist ein Commit.
• Ein Branch besteht aus einer Kette solcher abgehefteten Zwischenstände. So können Sie später jeden Schritt nachvollziehen.

Merge Request: Die Mappe zur Unterschrift

Sie sind mit Ihrer Arbeit fertig. Ihre Kopie ist nun besser und aktueller als das Original im Schrank. Aber Sie dürfen nicht einfach zum Schrank rennen und die Ordner austauschen.

Stattdessen legen Sie Ihre überarbeitete Mappe in die "Posteingangsschale" eines Kollegen (Reviewer) und stellen einen Antrag: "Bitte prüf das mal. Wenn alles okay ist, sortiere diese neuen Seiten bitte in den originalen Aktenschrank ein."

• Dieser formale Antrag zur Übernahme Ihrer Änderungen ist der Merge Request (MR).
• Hier findet die Qualitätssicherung statt. Kollegen können Anmerkungen machen ("Seite 5 ist noch unklar").
• Erst wenn alles passt, wird der Merge Request "gemerged" – also Ihre Kopie zum neuen Original im Aktenschrank gemacht.

Markdown: Das Manuskript

In den Aktenordnern selbst nutzen wir keine Word-Dokumente, sondern Markdown.

Analogie: Stellen Sie sich vor, Sie schreiben nicht direkt in das fertige Hochglanz-Magazin, sondern tippen ein rohes Manuskript auf der Schreibmaschine. Da Sie dort keine Knöpfe für "Fett" oder "Überschrift" haben, nutzen Sie vereinbarte Kürzel (Regieanweisungen) für den Setzer.

• Ein # am Zeilenanfang bedeutet: "Bitte mach aus dem folgenden Satz später eine große Überschrift."
• Sternchen ** um ein Wort herum bedeuten: "Bitte drucke das Wort dazwischen fett."

Fachlicher Hintergrund: Markdown ist eine leichtgewichtige Auszeichnungssprache und weltweit Standard für technische Dokumentationen. Wir nutzen sie aus drei Gründen:

1. Fokus auf den Inhalt: Autor:innen kümmern sich nur um den Text. Um Schriftarten und Abstände kümmert sich später der "Verlag" (die Software).
2. Perfekte Versionskontrolle: Da Markdown reiner Text ist, kann GitLab jede noch so kleine Änderung Zeile für Zeile nachvollziehen ("Diffs"). Bei Word-Dateien wäre das technisch kaum möglich.
3. Zukunftssicherheit: Die Dateien sind mit jedem Texteditor lesbar.
   Das ist gegenüber Word, WordPerfect, WordStar, StarWriter und anderen (nicht mehr) unterstützten Dateiformaten ein wichtiger Vorteil.
4. Leichte Erlernbarkeit: Auch ohne Vorkenntnisse können Sie damit innerhalb einer Stunde produktiv Texte erstellen – HTML-Kenntnisse oder ähnliches sind nicht erforderlich.

Automatisierung: Die GitLab CI Pipeline

Sobald Sie einen Merge Request stellen oder eine Änderung speichern, springt im Hintergrund eine Maschine an: Die GitLab CI Pipeline (Continuous Integration).
Vergleichbar ist dies mit einer automatischen Formularprüfung in der Verwaltung. Sie garantiert Qualität und Sicherheit durch reproduzierbare Abläufe:

1. Build-Phase

   • Der Inhalt des Repositories (Markdown-Dokumente, Grafiken und andere Artefakte) wird in eine ausführbare Form überführt, in unserem Fall in eine Website.
   • Ziel: Grundlegende Syntaxfehler oder Abhängigkeitsprobleme früh erkennen.

2. Testphase

   • Automatisierte Tests prüfen Funktionen, Performance und Kompatibilität.
   • Beispiele: Unit-Tests, Integrationstests, UI-Tests.

3. Qualitätssicherung (QA)

   • Statische Code-Analyse (z. B. auf Sicherheitslücken oder Code-Standards).
   • Compliance-Checks (z. B. Lizenzkonformität, Dokumentation).

4. Bereitstellung (Deployment)

   • Bei erfolgreichen Tests für noch nicht gemergte Änderungen: Automatisches Erstellen einer Preview-Umgebung, damit die Textänderungen vorab so geprüft werden können, wie sie nach dem Merge aussehen.
   • Auf manuelle Anforderung: Mergen der Änderungen in den main Branch.

Vorteile

Aspekt	Nutzen
Effizienz	Reduziert manuelle Wiederholungsaufgaben (z. B. Tests, Builds).
Konsistenz	Garantiert einheitliche Prüfkriterien für alle Änderungen.
Fehlererkennung	Probleme werden sofort gemeldet, bevor sie eskalieren.
Transparenz	Protokolliert jeden Schritt (Logfiles, Statusmeldungen).
Schnelligkeit	Beschleunigt die Bereitstellung neuer Features oder Fixes.

Die Rolle von Docusaurus

Innerhalb dieser Pipeline arbeitet die Software Docusaurus. Man kann sich Docusaurus als den automatischen Redakteur und Layouter vorstellen. Er übernimmt folgende Aufgaben:

1. Konvertierung: Er nimmt Ihr "Manuskript" (Markdown) und baut daraus die fertige, interaktive HTML-Webseite (mit Menüs, Suche, Design).
2. Qualitätskontrolle: Er prüft, ob alle internen Verlinkungen funktionieren (keine "Toten Links") und ob die Metadaten korrekt sind.

Das Ziel: docs.fitko.de

Wenn Ihr Merge Request akzeptiert wurde, sorgt die Pipeline abschließend dafür, dass der neue Stand auf docs.fitko.de veröffentlicht wird. Dies ist die zentrale Dokumentationsplattform des Föderalen Entwicklungsportals. Ihre Dokumentation erscheint dort in einem vereinbarten Bereich (z. B. meta), professionell formatiert und für alle zugänglich.