Vorüberlegungen

Ziel der Dokumentation

Bevor die erste Zeile Code geschrieben oder der erste Satz formuliert wird, muss klar sein, warum diese Dokumentation erstellt wird und für wen. Gerade in der öffentlichen Verwaltung, wo Dokumente oft als langlebige PDFs existieren, bietet eine Docusaurus-Website dynamische Vorteile.

Wenn Sie zunächst klären möchten, ob eine Dokumentationswebsite im Föderalen Entwicklungsportal für Ihre Organisation grundsätzlich sinnvoll ist, nutzen Sie die Seite Entscheidungshilfe.

Mögliche Zielsetzungen

• Single Source of Truth: Vermeidung veralteter Versionen auf lokalen Laufwerken – es gilt nur, was auf der Website steht.
• Entlastung des Supports (Shift Left): Nutzer finden Antworten auf häufige Fragen selbstständig, was Hotline und Ticketsystem entlastet.
• Onboarding und Schulung: Neue Mitarbeitende oder Externe arbeiten sich eigenständig in Prozesse oder Software ein.
• Barrierefreiheit und Durchsuchbarkeit: HTML-Inhalte sind leichter barrierefrei zu gestalten und besser durchsuchbar als komplexe PDF-Dokumente.
• Transparenz und Standardisierung: Einheitliche Darstellung von Schnittstellen (APIs) oder Verwaltungsprozessen.

Relevante Standards und Leitlinien

Für digitale Services der öffentlichen Verwaltung gelten insbesondere:

• Service Standard: (öffnet in neuem Tab) Verbindliche Orientierung für nutzerzentrierte Umsetzung, Qualität und Barrierefreiheit
• DIN SPEC 66336: (öffnet in neuem Tab) Relevant im Kontext von Standardisierung und Interoperabilität

Klärung vor Projektbeginn

Aufgabe für den Product Owner

Definieren Sie vor Projektstart eindeutig:

1. Was genau dokumentiert werden soll
2. Für wen die Dokumentation bestimmt ist (Zielgruppe)
3. Wozu sie erstellt wird (Zweck und Ziel)

Kommunizieren Sie diese Festlegungen an alle Beteiligten, um Unklarheiten von Beginn an zu vermeiden.

Beteiligte Rollen

Das Erstellen einer Dokumentationswebsite ist Teamsport. Verschiedene Akteure müssen zusammenarbeiten, damit das Ergebnis ein Erfolg wird. Diese haben wir nachfolgend aufgelistet.

Verantwortlichkeiten und Leistungen im Zusammenspiel

Die fachliche Verantwortung für Inhalte liegt bei Product Owner und Redaktionsteam. Das FEP-Kernteam berät und unterstützt immer dort, wo gemeinsame Plattformbausteine, Betrieb und technische Querschnittsleistungen erforderlich sind.

Erklärtext zur Infografik

Die detaillierte Darstellung trennt Aufgaben und Leistungen in fünf Felder:

• PO & Team: Fachverständnis, Schreibkompetenz, Informationsarchitektur, DevOps-Basics und kontinuierliche Dokumentationspflege.
• FEP-Kernteam: Docusaurus-Template, Meta-Dokumentation, integrierte Werkzeuge sowie Unterstützung und Beratung.
• Betrieb Portal: Laufender Betrieb zentraler Portal-Funktionen wie Verzeichnispflege, Link-Management und Software-Updates.

Für die Projektplanung bedeutet das:

• Die Produktseite steuert Inhalte, Prioritäten und Qualität.
• Das FEP-Kernteam schafft den technischen und organisatorischen Rahmen für einen stabilen Betrieb.

Erklärtext zur Infografik

Die Grafik zeigt eine abgestufte Verantwortungsverteilung:

• Fachverständnis und Dokumentationspflege liegen primär beim PO- und Autor:innenteam.
• Mit zunehmender technischer Komplexität steigt der Unterstützungsanteil des FEP-Kernteams.
• Informationsarchitektur und DevOps-Basics sind ein gemeinsamer Arbeitsbereich: inhaltlich durch das Produktteam, methodisch und technisch begleitet durch das Kernteam.

Rolle	Aufgaben und Verantwortlichkeiten
Product Owner (PO)	• Definiert die Zielgruppe und die strategischen Ziele der Dokumentation. • Priorisiert Inhalte und entscheidet über neue Themen. • Verwaltet Zugriffsrechte auf das Repository. • Nimmt die fertige Dokumentation ab (fachliche Freigabe). • Fungiert als Schnittstelle zu den Fachbereichen.
Redakteur:innen	• Geben Merge-Requests frei.
Autor:innen	• Verfassen die eigentlichen Inhalte (Markdown/MDX). • Erstellen Screenshots und Diagramme. • Pflegen bestehende Artikel und halten diese aktuell. • Setzen redaktionelle Vorgaben um.
FEP-Kernteam	• Stellt die Basisinfrastruktur/Templates (z.B. Corporate Design Vorgaben) bereit. • Konfiguriert CI/CD-Pipelines (automatisches Bauen und Veröffentlichen). • Stellt zentrale Komponenten (Suche, Glossar) bereit. • Spielt technische Updates ein (Docusaurus-Versionen, Plugins). • Berät übergreifend zu Best Practices.

Es liegt auf der Hand, dass sich Rollen personell überschneiden können, d.h. eine Person agiert in mehreren Rollen. Insbesondere bei kleinen Dokumentationsteams ist dies eher die Regel als die Ausnahme.

Veröffentlichungsstrategie

Für Dokumentationswebsites bieten sich zwei verschiedene Strategien an:

• Strategie "Kontinuierliche Updates" (Rolling Release)
  Verbesserungen und Ergänzungen werden fortlaufend eingepflegt und zeitnah veröffentlicht. Änderungen werden über ein Changelog nachvollziehbar gemacht, eine formale Versionierung (z. B. v1.0, v1.1) findet jedoch nicht statt. Der Nutzer sieht immer den aktuellsten Stand. Ideal für: Prozesshandbücher, FAQs, Wikis.
• Strategie "Versionierung" (Snapshot-Releases)
  Änderungen werden zunächst gesammelt und intern begutachtet (Entwurfsstand der nächsten Version, oft „Next“ genannt). Die Veröffentlichung erfolgt gebündelt in formellen Versionen in größeren Zeitabständen. Ein großer Vorteil von Docusaurus ist hierbei, dass Nutzer auf der Website bei Bedarf auch auf ältere Dokumentationsstände zugreifen können. Ideal für: Software-Dokumentation (passend zur Software-Version) und API-Spezifikationen.

Weitere organisatorische Aspekte

Neben den Rollen und der Technik (Docusaurus) müssen vor dem Start folgende organisatorische Rahmenbedingungen geklärt sein, um "Wildwuchs" zu vermeiden:

Redaktionsleitfaden (Style Guide)

Damit die Dokumentation wie "aus einem Guss" wirkt, auch wenn mehrere Autoren daran schreiben, braucht es Regeln:

• Tonalität: Duzen oder Siezen wir die Leser:innen? (In der Verwaltung meist "Sie", in Entwicklungsdokumentationen oft "Du").
• Sprache: Deutsch, Englisch oder Zweisprachigkeit (i18n)?
• Formatierung: Wie werden Warnhinweise, Code-Blöcke oder Bilder beschriftet?
• Farben, Grafiken: Wird ein Produkt des IT-Plaungsrats dokumentiert, ist der ensprechende Brand Guide zu beachten.
• Glossar: Definition zentraler Begriffe zur einheitlichen Verwendung.

Tipp

Die IT-PLR-Farbpalette ist in der Datei /tailwind.config.js hinterlegt. Die darin enthaltenen Farbwerte können beispielsweise für die Erstellung von Grafiken verwendet werden.

Qualitätssicherung & Review-Prozess

Wer darf wann veröffentlichen?

• Vier-Augen-Prinzip: Jeder Artikel sollte mindestens von einer zweiten Person gegengelesen werden (inhaltlich und sprachlich).
• Pull-Request-Workflow: Technisch kann dies über GitLab gut abgebildet werden (Autoren reichen Änderungen ein, PO oder Redakteur:innen "mergen" diese).

Feedback-Kultur (Feedback Loop)

Eine Dokumentation lebt. Wie melden Nutzer Fehler oder Wünsche?

In der Praxis verweisen "Seite bearbeiten"-Links oder "Feedback"-Links häufig auf ein Git-Repository (im FEP-Kontext meist auf gitlab.opencode.de). Dafür benötigen Nutzer jedoch einen openCode-Account. Das kann insbesondere für externe Zielgruppen oder Gelegenheitsnutzer eine spürbare Hürde darstellen.

Deshalb gilt: Bieten Sie immer mindestens einen niedrigschwelligen alternativen Feedback-Kanal an, zum Beispiel:

• eine gut sichtbare E-Mail-Adresse
• ein Kontaktformular

Empfehlung

Ein Link zum Repository kann ergänzend sinnvoll sein – er sollte jedoch nicht der einzige Weg für Rückmeldungen sein.

Legen Sie außerdem verbindlich fest:

• Wer sichtet und bearbeitet eingehendes Feedback regelmäßig?
• Wie wird sichergestellt, dass eingehende Hinweise nicht übersehen werden?

Wichtig bei GitLab-Issues

Bei Issues auf gitlab.opencode.de müssen zuständige Personen das Projekt bzw. den Issue-Bereich aktiv abonnieren ("Beobachten"), damit sie Benachrichtigungen erhalten, wenn neue Issues erstellt oder kommentiert werden. Andernfalls besteht die Gefahr, dass Rückmeldungen zwar technisch eingehen, aber organisatorisch nicht wahrgenommen werden.

Rechtliche Rahmenbedingungen

Da es sich um die öffentliche Verwaltung handelt, sind folgende Punkte zwingend vor Go-Live zu klären:

• Datenschutz: Datenschutzerklärung einbinden (insb. wenn Tracking/Analytics genutzt wird).
• Impressum: Korrekte Anbieterkennzeichnung.
• Barrierefreiheit: Für das Föderale Entwicklungsportal gilt die Erklärung zur Barrierefreiheit der FITKO (öffnet in neuem Tab). Eine eigene Erklärung zur Barrierefreiheit für die jeweilige Dokumentationswebsite ist daher nicht erforderlich. Es ist jedoch unbedingt darauf zu achten, dass die dort als „erfüllt“ angegebenen Anforderungen auch von jeder Dokumentationswebsite erfüllt werden.

Information

Wird das Docusaurus-Template des Föderalen Entwicklungsportals verwendet, gibt es hinsichtlich Impressum und Datenschutz kein To-do: Es gilt das Impressum der FITKO und die Datenschutzerklärung des Föderalen Entwicklungsportals. Diese sind auch in dieser Online-Dokumentation im Seitenfuß entsprechend verlinkt, siehe unten.

Barrierefreiheit in Inhalten

Auch wenn Docusaurus beim Erstellen barrierearmer Websites unterstützt, bleibt Barrierefreiheit eine Aufgabe im Redaktionsalltag. Das ist besonders wichtig, weil jede Dokumentationswebsite die Anforderungen erfüllen muss, die in der Barrierefreiheitserklärung der FITKO für das Föderale Entwicklungsportal als „erfüllt“ angegeben sind.

Besonders bei Grafiken gilt:

• Alt-Texte setzen: Jede inhaltliche Grafik braucht einen kurzen, zweckorientierten Alt-Text.
• Komplexe Grafiken erläutern: Bei Diagrammen oder Abläufen zusätzlich eine Erklärung direkt unterhalb ergänzen.
• Text in Bildern vermeiden: Inhalte, die wichtig sind, besser als Fließtext statt als „eingebrannter“ Screenshot.

Eine kurze, praxisorientierte Checkliste und weiterführende Links finden Sie auf der Seite Barrierefreiheit.