Dokumentationstypen der IsyFact

Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Übersicht über die Typen der Dokumentation

Im Folgenden werden die Dokumentationstypen der IsyFact erläutert. Neben einer kurzen Beschreibung des Ziels und Inhalts werden die Zielgruppen und der Scope benannt. Unter Vorlage / Beispiel findet sich ein Verweis auf vordefinierte Vorlagen oder ein repräsentatives konkretes Beispiel.

1. Säule Blaupausen

Blaupausen werden mit folgenden Dokumentationstypen beschrieben:

Tabelle 1. Referenzarchitektur
Referenzarchitektur
Ziel	Die Referenzarchitektur definiert einen Strukturierungsrahmen für die Anwendungslandschaft und legt Prinzipien für die softwaretechnische Realisierung fest.
Inhalt	Definition einheitlicher Vorgaben unter Berücksichtigung fachlicher und technischer Anforderungen bezogen auf die Architektur einer Anwendung bzw. Anwendungslandschaft. Enthält drei Architektursichten: fachlich, software-technisch, technische Infrastruktur. Enthält Architekturvorgaben und Architekturentscheidungen.
Zielgruppe(n)	Architekten, (Entwickler)
Scope	Blaupause
Vorlage / Beispiel	Referenzarchitektur

Tabelle 2. Detailkonzept
Detailkonzept
Ziel	Vorgaben zur Umsetzung bezogen auf eine Blaupause, sofern sie eine technische Ausrichtung haben.
Inhalt	Beschreibt Blaupausen für software-technische Architektur wie z.B. Batches, Datenzugriffe oder Services. Enthält Architekturvorgaben und Architekturentscheidungen.
Zielgruppe(n)	Architekten, Entwickler, (IT-Betrieb)
Scope	Blaupause
Vorlage / Beispiel	Detailkonzept Komponente Datenzugriff

2. Säule Bausteine

Bausteine werden mit folgenden Dokumentationstypen beschrieben:

Tabelle 3. Konzept
Konzept
Ziel	Definition einheitlicher Vorgaben unter Berücksichtigung fachlicher und technischer Anforderungen bezogen auf einen Baustein.
Inhalt	Technische Feinkonzeption Anforderungen Architekturvorgaben und Architekturentscheidungen
Zielgruppe(n)	Architekten, (Entwickler)
Scope	Baustein (Bibliothek)
Vorlage / Beispiel	Konzept JPA/Hibernate

Tabelle 4. Nutzungsvorgaben
Nutzungsvorgaben
Ziel	Vorgaben zur Nutzung eines Bausteins in der Entwicklung.
Inhalt	Beschreibung, wie ein konkreter Baustein (Bibliothek) für die Entwicklung einer Anwendung genutzt werden kann. Hinweise zur Verwendung oder Konfiguration von externen Bibliotheken oder Produkten, sofern Teil des Bausteins. Nutzungsvorgaben sind keine Benutzerdokumentation.
Zielgruppe(n)	Entwickler
Scope	Baustein (Bibliothek)
Vorlage / Beispiel	Nutzungsvorgaben JPA/Hibernate

Tabelle 5. Changelog
Changelog
Ziel	Änderungsdokumentation eines Bausteins.
Inhalt	Textuelle Beschreibung der Änderungen, nach Releases geordnet.
Zielgruppe(n)	Architekten, Entwickler
Scope	Baustein (allgemein)
Vorlage / Beispiel	Vorgaben zu Changelogs Changelog der IsyFact

Tabelle 6. Systemspezifikation
Systemspezifikation
Ziel	Fachlichkeit des Systems spezifizieren (Grundlage der (Weiter-)Entwicklung) und dokumentieren.
Inhalt	Gliederung für eine V-Modell-konforme Gesamtsystemspezifikation (Pflichtenheft) eines Softwaresystems (Software-Entwicklungsprojekts): Fachliche Anforderungen in Form von Anwendungsfällen und Anwendungsfunktionen, Fachliches Datenmodell, Dialoge und Masken, Nachbarsystemschnittstellen, Nichtfunktionale Anforderungen. Zu bestimmten Meilensteinen werden alle Systemspezifikationen einer Anwendungslandschaft mit den implementierten Teilen in einer Masterspezifikation konsolidiert zusammengefasst. Dies macht sie zu einer Dokumentation.
Zielgruppe(n)	Fachabteilung, fachliche und technische Architekten, Entwickler, (alle)
Scope	Baustein (QA)
Vorlage / Beispiel	Vorlage

Tabelle 7. Fachliche Schnittstellenspezifikation
Fachliche Schnittstellenspezifikation
Ziel	Fachliche Beschreibung einer angebotenen (oder genutzten) Schnittstelle.
Inhalt	Kommunikationsabläufe Nachbarschnittstellen Angebotene Schnittstelle (vom BVA nach extern angebotene Schnittstelle) Benutzte Schnittstelle (BVA-fremde Schnittstelle, sofern keine Dokumentation besteht) fachliche Datentypen Fehlerbehandlung Schnittstellenverhalten Weitergehende Informationen Abgrenzung zur technischen Schnittstellenspezifikation.
Zielgruppe(n)	Fachabteilung, fachliche und technische Architekten, Entwickler, Nutzer der Schnittstelle, (alle)
Scope	Baustein (QA)
Vorlage / Beispiel	Vorlage

Tabelle 8. Systementwurf
Systementwurf
Ziel	Technische Beschreibung des Systems
Inhalt	Grundlage zur Abstimmung zwischen Architekten und IT-Betrieb Vorgabe und Anleitung für Software-Entwickler Systemabgrenzung (Kontextübersicht) Randbedingungen und Annahmen Systemarchitektur (vermutlich Level 1 Blackbox?) nichtfunktionale Anforderungen TI-Architektur (Deployment View) Externe Bibliotheken und Drittsoftware Datenmodell Architektur der Teilsysteme (vermutlich Level 2 und niedriger White- und Black-Box) Querschnittliche Konzepte
Zielgruppe(n)	Architekten, Entwickler, IT-Betrieb
Scope	Baustein (QA)
Vorlage / Beispiel	Vorlagen Vorlage Systementwurf

Tabelle 9. Technische Schnittstellendokumentation
Technische Schnittstellendokumentation
Ziel	Technische Beschreibung einer Schnittstelle mit dem Ziel, die Anbindung der Schnittstelle aus technischer Sicht zu erläutern.
Inhalt	Schnittstellenbeschreibung Ressourcen und zugehörige Verben URLs Request/Response Content Type Technisches Datenmodell Format der Requests Format der Responses Status Codes Fehlermeldungen Abgrenzung zur fachlichen Schnittstellenspezifikation.
Zielgruppe(n)	Entwickler, Architekten, IT-Betrieb
Scope	Baustein (QA)
Vorlage / Beispiel	REST / OpenAPI: Für REST-Schnittstellen erfolgt die Erstellung gemäß der Nutzungsvorgaben des REST-Bausteins.

Tabelle 10. Systemhandbuch
Systemhandbuch
Ziel	Beschreibung der für Betrieb von Anwendungen erforderlichen Aspekte OHNE umgebungsspezifische Konfiguration.
Inhalt	Technische und fachliche Verfahrensbeschreibung Beschreibung der TI-Architektur (allgemein) Beschreibung des regulären Wirkbetriebs Installation & Konfiguration (ohne konkrete Parameter von Umgebungen) Verwendung der Batches Hinweise zur Fehler- und Störungsdiagnose und -behandlung Hinweise zum Backup Abgrenzung: Das Systemhandbuch enthält nur solche Informationen, welche die eigentliche Software betreffen. Informationen zu Systemumgebungen, Hardware usw. werden vom Betrieb in separaten Dokumenten gepflegt, die nicht über die IsyFact standardisiert sind.
Zielgruppe(n)	IT-Betrieb
Scope	Baustein (QA)
Vorlage / Beispiel	Vorlagen Vorlage Systemhandbuch

Tabelle 11. Anwenderhandbuch
Anwenderhandbuch
Ziel	Bedienungshinweise zur Benutzeroberfläche für Anwender von fachlichen Anwendungssystemen oder Querschnittsanwendungen.
Inhalt	Bedienungsanleitung für die Benutzeroberfläche (GUI)
Zielgruppe(n)	Anwender
Scope	Baustein (QA)

Tabelle 12. Produktkatalog
Produktkatalog
Ziel	Dokumentation der verwendeten Produkte
Inhalt	Informationen zu den Produkten Unterteilung nach allgemeinen Produktvorgaben und den Technologie-Stacks Definition eines Lebenszyklus für Produkte
Zielgruppe(n)	Anwender
Scope	Baustein (QA)
Vorlage / Beispiel	Allgemeine Produktvorgaben Produkte für Java/Spring, Typescript/Angular Lebenszyklus Negativliste

3. Säule Plattform

Infrastrukturkomponenten aus der Säule Plattform können mit dem folgenden Dokumentationstyp beschrieben werden:

Tabelle 13. Nutzungskonzept
Nutzungskonzept
Ziel	Vorgaben zur Nutzung einer Infrastrukturkomponente innerhalb der Plattform, die aus einem Standardprodukt besteht.
Inhalt	Architekturüberblick Beschreibung des regulären Wirkbetriebs Installation & Konfiguration der Komponente Aktualisierung des Produkts Hinweise zur Fehler- und Störungsdiagnose und -behandlung
Zielgruppe(n)	Architekten, Entwickler
Scope	Plattform

4. Säule Methodik

Die Methodik wird mit folgendem Dokumentationstyp beschrieben:

Tabelle 14. Themenseite Methodik
Themenseite Methodik
Ziel	Beschreibung von Konventionen oder Vorgaben, die zu einer Methodik oder einem Vorgehensmodell gehören.
Inhalt	Beschreibung des Themas (s. Vorlage/Beispiel)
Zielgruppe(n)	je nach Thema (meist Architekten, Entwickler, technische Autoren)
Scope	Methodik
Vorlage / Beispiel	Erstellung von Seiten

5. Säule Werkzeuge

Werkzeuge werden mit folgendem Dokumentationstyp beschrieben:

Tabelle 15. Themenseite Werkzeug
Themenseite Werkzeug
Ziel	Beschreibung von Konventionen oder Vorgaben, die zu einem Werkzeug gehören.
Inhalt	Beschreibung des Werkzeugs (s. Vorlage/Beispiel)
Zielgruppe(n)	je nach Thema (meist Architekten, Entwickler, technische Autoren)
Scope	Werkzeug
Vorlage / Beispiel	Erstellung von Seiten Handbuch diagrams.net