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