Dokumentationstypen der IsyFact

IFS-Logo 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 Referenzarchitektur

Die Referenzarchitektur wird mit folgenden Dokumentationstypen beschrieben:

Tabelle 1. Themenseite Referenzarchitektur
Themenseite Referenzarchitektur

Ziel

Definition einheitlicher Vorgaben unter Berücksichtigung fachlicher, technischer und betrieblicher Anforderungen bezogen auf die Architektur einer Anwendung bzw. Anwendungslandschaft.

Inhalt

Thematisch zusammenhängende Seiten mit den folgenden Eigenschaften:

  • gegliedert nach drei Architektursichten: fachlich, software-technisch, technisch-infrastrukturell,

  • enthält Architekturvorgaben und setzt Architekturentscheidungen um.

Zielgruppe(n)

Architekten, (Entwickler)

Scope

Referenzarchitektur

Vorlage / Beispiel

Vorlage:

Beispiele:

2. Säule Bausteine

Bausteine werden mit folgenden Dokumentationstypen beschrieben:

Tabelle 2. Konzept
Konzept

Ziel

Definition einheitlicher Vorgaben unter Berücksichtigung fachlicher und technischer Anforderungen bezogen auf einen Baustein.

Inhalt

  • Technische Feinkonzeption mit Lösungsansatz

  • Anforderungen

  • Architekturvorgaben, Rahmenbedingungen und Architekturentscheidungen

Zielgruppe(n)

Architekten, (Entwickler)

Scope

Baustein (Bibliothek)

Vorlage / Beispiel

Konzept JPA/Hibernate
Tabelle 3. Nutzungsvorgaben
Nutzungsvorgaben

Ziel

Vorgaben zur Nutzung eines Bausteins in der Entwicklung (aus technischer Sicht).

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 und komplementieren das Konzept.

Zielgruppe(n)

Entwickler

Scope

Baustein (Bibliothek)

Vorlage / Beispiel

Nutzungsvorgaben JPA/Hibernate
Tabelle 4. 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
Tabelle 5. 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 6. 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 7. 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
Tabelle 8. 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 9. 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
Tabelle 10. Anwenderhandbuch
Anwenderhandbuch

Ziel

Bedienungshinweise für Anwender zur grafischen Benutzeroberfläche von Anwendungen.

Inhalt

  • Bedienungsanleitung für die Benutzeroberfläche (GUI)

Zielgruppe(n)

Anwender

Scope

Baustein (QA)
Tabelle 11. 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

3. Säule Plattform

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

Tabelle 12. 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 13. 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 14. 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