Architektur der Dokumentation¶

Überblick¶

Die Dokumentation der Feuerwehr Aidlingen basiert auf bewährten Open-Source-Technologien und folgt modernen Standards für technische Dokumentation.

Important

Keine Sorge! Als Autor müssen Sie die technischen Details nicht kennen. Dieser Abschnitt erklärt, wie das System im Hintergrund funktioniert.

Technologie-Stack¶

Sphinx: Dokumentationsgenerator - erstellt aus Textdateien eine moderne Website
Furo Theme: Modernes, responsives Design für optimale Lesbarkeit
Python: Programmiersprache für Build-Prozess und Erweiterungen
Git / GitLab: Versionskontrolle und Zusammenarbeit

System-Architektur (vereinfacht)¶

Die Dokumentation durchläuft mehrere Schritte:

Erstellung: Autoren schreiben Inhalte in einfachen Textdateien
Verarbeitung: Sphinx wandelt die Textdateien in HTML um
Veröffentlichung: Die fertige Website wird auf einem Server bereitgestellt

Dateiformat und Struktur¶

Unterstützte Formate¶

Format	Verwendung	Vorteil
RST (reStructuredText)	Technische Dokumentation, komplexe Layouts	Sehr mächtig, viele Features
Markdown	Einfache Texte, Listen, Tabellen	Einfach zu lernen, weit verbreitet
PDF/Bilder	Bestehende Dokumente, Grafiken	Kann direkt eingebunden werden

Verzeichnisstruktur¶

Die Dokumentation ist logisch in Hauptbereiche gegliedert:

ffw_doc/
├── 00-doku-konzept/      # Dieses Kapitel
├── 01-organisation/      # Struktur, Gerätehaus, Onboarding
├── 02-regelwerke/        # Vorschriften, AAO
├── 03-wissen/            # Ausbildung, Digitalfunk
├── 04-einsatzmittel/     # Fahrzeuge, Geräte
├── _static/              # Bilder, PDFs, CSS
│   ├── images/
│   └── pdf/
└── _templates/           # Vorlagen für neue Seiten

Tip

Die Nummerierung (00, 01, 02…) bestimmt die Reihenfolge im Hauptmenü.

Komponenten-Architektur¶

Organisation der Inhalte¶

Jedes Hauptkapitel folgt demselben Muster¶

kapitel-name/
├── index.rst              # Übersichtsseite des Kapitels
├── unterkapitel-1.rst     # Einzelne Seiten
├── unterkapitel-2.rst
└── bilder/                # Kapitel-spezifische Bilder (optional)

Verlinkung zwischen Seiten¶

Seiten können miteinander verlinkt werden:

# Verweis auf eine andere Seite
Siehe :doc:`../01-organisation/onboarding/neuaufnahme`

# Verweis auf einen Abschnitt
Siehe :ref:`doku-konzept-why`

Build-Prozess¶

Lokale Entwicklung¶

Für Redakteure, die lokal arbeiten:

# Voraussetzungen installieren
poetry install

# Dokumentation bauen
poetry run sphinx-build -b html . build/

# Live-Vorschau mit automatischem Reload
poetry run sphinx-autobuild . build/

Note

Die meisten Autoren müssen dies nicht selbst ausführen - sie können Änderungen einfach als Merge Request einreichen.

Automatische Builds (CI/CD)¶

Bei jeder Änderung:

Automatische Prüfung der Rechtschreibung
Validierung aller Links
Bauen der HTML-Ausgabe
Bei Erfolg: Automatische Veröffentlichung

Qualitätssicherung¶

Automatische Checks¶

Rechtschreibprüfung: Erkennt Tippfehler
Link-Validierung: Prüft ob alle Verweise funktionieren
Syntax-Prüfung: Stellt sicher, dass die Dateien korrekt formatiert sind
Bild-Validierung: Prüft, ob alle referenzierten Bilder existieren

Erweiterbarkeit¶

Die Architektur ist erweiterbar für zukünftige Anforderungen:

Erweiterte Suche: Integration von Suchmaschinenoptimierung
Mobile App: Native Apps für iOS/Android möglich
Zugriffskontrolle: Geschützte Bereiche für interne Infos
Mehrsprachigkeit: Übersetzungen in andere Sprachen
Analytics: Nutzungsstatistiken und Zugriffsanalysen
API-Integration: Anbindung an andere Systeme

Performance & Verfügbarkeit¶

Schnelle Ladezeiten: Statische HTML-Seiten laden sehr schnell
Offline-Fähigkeit: Browser können Seiten für Offline-Nutzung cachen
Skalierbarkeit: Beliebig viele Seiten und Nutzer möglich
Backup & Versionierung: Alle Änderungen sind in Git gesichert und wiederherstellbar

Technische Abhängigkeiten¶

Komponente	Version	Zweck
Python	3.10+	Build-System
Sphinx	8.0+	Dokumentationsgenerator
Furo	aktuell	Theme/Design
MyST Parser	aktuell	Markdown-Unterstützung
Sphinx-Design	aktuell	UI-Komponenten (Karten, Grids)
PlantUML	aktuell	Diagramme
sphinxcontrib-spelling	aktuell	Rechtschreibprüfung