ESW-Dokumentationsstandards¶
Zweck¶
Dieses Verzeichnis definiert die verbindlichen Standards für die technische und organisatorische Dokumentation im Projekt ESW (Einsatz-Software).
Die hier festgelegten Regeln bilden die Grundlage für: - die Struktur und Inhalte der Projektdokumentation - die einheitliche Verwendung von Begriffen und Modellen - die Erstellung von Architektur-, Entscheidungs- und Betriebsdokumenten - die automatisierte Prüfung der Dokumentation in CI/CD
Diese Standards sind versioniert und Bestandteil des Projekts.
Geltungsbereich¶
Die in diesem Verzeichnis definierten Standards gelten für:
- alle Inhalte im Verzeichnis
docs/ - alle Architektur- und Design-Dokumente
- alle Architecture Decision Records (ADR)
- alle Diagramme (z. B. PlantUML, C4)
- alle projektrelevanten Beschreibungen und technischen Texte
Nicht umfasst sind: - rein technische Konfigurationsdateien ohne Dokumentationscharakter - externe Dokumentationen außerhalb des Projekts
Verbindlichkeit¶
Die Einhaltung dieser Standards ist verpflichtend.
- Abweichungen sind nur zulässig, wenn sie fachlich begründet und dokumentiert sind.
- Automatisierte Prüfungen in CI/CD setzen diese Standards um.
- Verstöße können zum Fehlschlagen von Pipelines führen.
Maßgeblich sind ausschließlich die hier definierten ESW-Standards – nicht externe Vorlagen oder Originalmodelle.
Bezug zu etablierten Standards¶
ESW orientiert sich an bewährten internationalen Standards der Softwareentwicklung und Architektur, insbesondere:
- arc42 (Architekturdokumentation)
- C4-Modell (Visualisierung von Systemarchitektur)
- ADR (Architecture Decision Records)
Diese Modelle werden fachlich übernommen, jedoch sprachlich und strukturell an ESW angepasst.
Sprache¶
Die Projektsprache von ESW ist Deutsch.
Begründung: - ESW wird primär im deutschsprachigen Kontext eingesetzt - alle Entwickler und Anwender arbeiten auf Deutsch - Missverständnisse durch Sprachwechsel sollen vermieden werden
Daraus folgt:
- Dokumente werden grundsätzlich auf Deutsch verfasst
- Kapitel, Überschriften und Begriffe werden eingedeutscht
- englische Originalbezeichnungen werden nicht erzwungen
Ausnahmen: - etablierte Fachbegriffe ohne sinnvolle deutsche Entsprechung - technische Bezeichner (z. B. Code, Protokolle, APIs)
Grundprinzipien¶
Die Dokumentation im Projekt ESW folgt diesen Prinzipien:
1. Einheitlichkeit¶
Alle Dokumente folgen klar definierten Strukturen und Begriffen.
2. Verständlichkeit¶
Die Dokumentation ist für technisch versierte Anwender nachvollziehbar und konsistent.
3. Nachvollziehbarkeit¶
Entscheidungen und Architekturen sind dauerhaft dokumentiert und begründet.
4. Automatisierbarkeit¶
Die Struktur der Dokumentation ist so gestaltet, dass sie technisch überprüfbar ist.
5. Trennung von Norm und Inhalt¶
- Standards definieren, wie dokumentiert wird
- Fachdokumente enthalten die eigentlichen Inhalte
Struktur der Standards¶
Dieses Verzeichnis enthält folgende Teilstandards:
-
esw-architekturstandard.md
Definition der Architekturdokumentation basierend auf arc42 (eingedeutscht) -
esw-adr-standard.md
Vorgaben für Architekturentscheidungen -
esw-diagrammstandard.md
Regeln für Diagramme (PlantUML, C4, Kroki) -
esw-dokumentationsstandard.md
Allgemeine Regeln für Dokumente und Struktur -
esw-sprachstandard.md
Vorgaben zur Sprache und Terminologie -
esw-ci-standard.md
Beschreibung der automatisierten Prüfungen -
begriffsabbildung-standards.md
Zuordnung zwischen internationalen Modellen und ESW-Begriffen
Verhältnis zu CI/CD¶
Die CI/CD-Pipelines des Projekts setzen diese Standards technisch um.
Das bedeutet: - Strukturregeln werden automatisch geprüft - Formatierungsregeln werden validiert - Inhalte können teilweise semantisch überprüft werden
Die Pipeline ist somit Umsetzung, nicht Definition der Standards.
Weiterentwicklung¶
Die Standards werden kontinuierlich weiterentwickelt.
Änderungen erfolgen: - versioniert im Repository - nachvollziehbar über Commits und Merge Requests - abgestimmt innerhalb des Projekts
Ziel ist eine langfristig stabile, nachvollziehbare und automatisierbare Dokumentationsbasis.
Zusammenfassung¶
Die ESW-Dokumentationsstandards stellen sicher, dass:
- alle Dokumente einheitlich aufgebaut sind
- Architektur nachvollziehbar beschrieben ist
- Entscheidungen dauerhaft dokumentiert werden
- die Dokumentation automatisiert geprüft werden kann
- internationale Standards sinnvoll in den deutschen Kontext übertragen werden