Leitfaden Dokumentation
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.
Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.
Diese Seiten dienen technischen Autoren der Online-Dokumentation als Wegweiser. Die Online-Dokumentation wird nach festgelegten Regeln und nach einem bestimmten Grundschema angefertigt.
1. Grundlagen der Online-Dokumentation
Die Online-Dokumentation basiert auf AsciiDoc als Quellformat und auf Antora als Werkzeug zur Verarbeitung der Quellen. Veröffentlicht wird die Online-Dokumentation auf Github Pages mithilfe von Github Actions.
1.1. AsciiDoc
Die Online-Dokumentation wird in AsciiDoc verfasst. AsciiDoc ist textbasiert und bietet viele Möglichkeiten, Inhalte zu formatieren und strukturieren. Es eignet sich daher auch besonders gut dazu, in einem modernen Versionsverwaltungssystem parallel zu Quellcode o.ä. verwaltet zu werden. Für AsciiDoc gibt es zahlreiche Generatoren, um Quelldokumente in HTML, PDF, E-Book- oder Wiki-Formate umzuwandeln.
1.2. Antora
Die Online-Dokumentation wird mit Antora generiert. Antora erzeugt aus AsciiDoc-Quellen, die über mehrere Git-Repositories verteilt liegen können, eine gemeinsame, statische HTML-Seite, auch Projektseite genannt. Eine besondere Stärke von Antora ist die Git-Integration, die es ermöglicht, Branches und Tags zu verwenden, um verschiedene Versionen derselben Dokumentation zu erzeugen.
Einzelheiten zur Dokumentation mit Antora finden sich auf den Unterseiten des Leitfadens.
1.3. Werkzeuge
In der Arbeitsumgebung müssen Git, Git LFS sowie npm installiert sein. Diese Werkzeuge reichen aus, um eine Projektseite zu erzeugen.
Zum Erstellen und Bearbeiten von AsciiDoc-Quellen ist zusätzlich ein fähiger Editor nötig. Empfohlen seien an dieser Stelle:
-
Visual Studio Code zusammen mit der Erweiterung für AsciiDoc,
-
Editoren von IDEs (u.a. IntelliJ IDEA oder Eclipse), sofern eine Unterstützung für AsciiDoc vorhanden ist.
2. Struktur der Quellen
Die Quellen der Online-Dokumentation der IsyFact verteilen sich auf mehrere Git-Repositories. Zur Bereitstellung der Projektseite nutzt die IsyFact zwei übergreifende Repositories:
-
isyfact.github.io zur Ablage der globalen Konfiguration (Playbook, CI/CD-Build, …) und zur Bereitstellung der erzeugten Projektseite,
-
isy-documentation zur Bereitstellung übergreifender Inhalte wie z.B. Lizenzhinweise, dem Glossar und einem Quellenverzeichnis.
Die meisten Inhalte sind derzeit im zentralen Repository isyfact-standards enthalten. Weitere Inhalte sind im Playbook referenziert.
2.1. Struktur des zentralen Repositories
Die Dokumentation ist vollständig im Modul isyfact-standards-doc enthalten. Sie unterteilt sich in Module, die sich an den Säulen der IsyFact bzw. an ihren Bausteinen orientieren.
| Modul | Beschreibung |
|---|---|
|
Einstieg in die IsyFact & Inhalte zur IsyFact allgemein |
|
→ |
|
Inhalte der Säule Referenzarchitektur |
|
Allgemeine Inhalte der Säule Bausteine |
|
Inhalte des jeweiligen Bausteins |
|
Inhalte der Säule Plattform |
|
Inhalte der Säule Methodik |
|
Inhalte der Säule Werkzeuge |
|
→ |
|
Änderungsdokumentation zum aktuellen Release |