Föderale IT-Architekturrichtlinien | Neu: Öffentliche Dokumentation
Es soll eine Architekturrichtlinie zur offenen, entwicklungsfokussierten Dokumentation zur Nutzung von Basiskomponenten ergänzt werden.
Reifegradmodell
- Stufe 0: Es liegt keine öffentliche Dokumentation zur Basiskomponente vor oder die Dokumentation liegt ganz oder teilweise nur im PDF-Format vor.
- Stufe 1: Die Dokumentation liegt vollständig inkl. aller benötigten Artefakte (OpenAPI-Spezifikationen, Beschreibung von Datenformaten, etc.) als öffentlich zugängliche Webseite vor.
- Stufe 2: Es sind Feedback-Kanäle zur Rückmeldung von Fehlern und Verbesserungsvorschlägen in der Dokumentation eingerichtet.
- Stufe 3: Die Dokumentation wird in einer öffentlich zugänglichen, Git-basierten Versionsverwaltung gepflegt. Auch Dritte können Änderungsvorschläge in Form von Merge-Requests einbringen. Fehler und Verbesserungsvorschläge können in einem öffentlich einsehbaren Issue-Tracker gemeldet werden ("Documentation as Code").
Empfehlungen
- Mit dem Föderalen Entwicklungsportal steht ein Produkt des IT-Planungsrates zur Pflege und Bereitstellung von technischer Dokumentation zur Verfügung. Dokumentation kann auf Basis des Open-Source-Tools Docusaurus auf der OpenCoDE-Plattform verwaltet und auf der Webseite docs.fitko.de bereitgestellt werden.
- Als Textauszeichnungssprache für technische Dokumentation wird Markdown empfohlen.
- Die Dokumentation sollte alle Aspekte der Nutzung der IT-Komponente beinhalten, insb. eine Architekturdokumentation auf Basis von arc42 und dem C4-Modell sowie einen Anbindungsleitfaden mit technischen, organisatorischen und rechtlichen Aspekten der Nutzung inkl. Code-Beispielen und Verweisen auf offizielle und inoffizielle SDKs
Edited by Marco Holz