Erstellung von Seiten

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.

Die Online-Dokumentation besteht im Wesentlichen aus Seiten. Dieser Guide beschreibt, was bei der Erstellung einer Seite wichtig ist.

Zum schnellen Anlegen einer neuen Seite steht eine Kopiervorlage bereit.

1. Strukturierung von Themen

Eine Seite behandelt ein bestimmtes, in sich selbst abgeschlossenes Thema. Führt die Beschreibung des Themas zu einer zu langen Seite, sollten einzelne Teilaspekte auf in sich selbst abgeschlossene Seiten ausgelagert werden. In sich selbst abgeschlossen bedeutet, dass zum grundlegenden Verständnis des Themas selbst (abzüglich der ausgelagerten Teilaspekte) nur die Seite selbst notwendig ist.

Listing 1. Dateiablage eines Themas

📄 thema.adoc (1)
📂 thema
  📄 teilaspekt-1.adoc (2)
  📄 teilaspekt-2.adoc
  📂 teilaspekt-2
      📄 teilaspekt-2-1.adoc
      📄 teilaspekt-2-2.adoc
  📄 ...
  📄 teilaspekt-n.adoc

1	Hauptseite eines Themas.
2	Seite zu einem Teilaspekt des Themas.

Diese Struktur kann rekursiv angewendet werden. Allerdings ist zu beachten, dass der Navigationsbaum hierdurch schnell unübersichtlich wird. Daher sollte es maximal zwei Ebenen unterhalb eines Themas geben.

2. Struktur einer Seite

Innerhalb einer Seite sollten nicht mehr als drei Gliederungsebenen benutzt werden. Eine tiefere Gliederung deutet darauf hin, dass die Seite:

zu umfangreich ist und aufgeteilt werden sollte, oder
dass Inhalte zu fein zerteilt werden.

Eine Seite enthält keine Beschreibung über sich selbst (z.B. in Form einer Einleitung). Das Inhaltsverzeichnis der Seite muss als "roter Faden" durch das Thema führen.

2.1. Seitentitel

Antora zeigt den Seitentitel an drei Stellen an:

als Überschrift der Seite,
im Breadcrumb darüber,
im Navigationsmenü am linken Rand.

Seitentitel sollten daher so kurz wie möglich und so lang wie nötig sein. Ist der Seitentitel für das Navigationsmenü zu lang, sollte in der Navigationsdatei (nav.adoc) des Antora-Moduls ein abgekürzter Seitentitel gesetzt werden.

2.2. Lizenzhinweis

Direkt nach dem Seitentitel steht der Lizenzhinweis. Dieser ist zentral definiert und kann einfach in die Seite eingebettet werden.

include::documentation-guide::partial$licence.adoc[]

2.3. Verweise auf andere Seiten

Verweise auf andere Seiten dienen in der Regel einem der folgenden Zwecke:

Sie verknüpfen Teilaspekte des Themas mit der entsprechenden Seite.
Sie machen auf Verbindungen zu anderen Themen aufmerksam.
Sie benennen externe Seiten, die der Vertiefung des Themas dienen.

Verweise sollten mit Bedacht eingesetzt werden. Zu viele Verweise stören den Lesefluss der Seite und lenken vom eigentlichen Thema ab. Ein gutes Format für optionale Verweise sind Admonition Blocks.

3. Formatierung

Der Quelltext einer Seite bricht gemäß der Regel one sentence per line nach jedem Satz um.

Mehr zu Zeilenumbrüchen hier.

3.1. Verweise

Es folgen Beispiele für seiteninterne Verweise auf eine Überschrift, ein Beispiel einer Abbildung, ein Beispiel einer Tabelle oder ein Beispiel eines Listings.

Verweise auf Seiten innerhalb derselben Dokumentation sind auf drei Ebenen möglich: innerhalb desselben Moduls, zwischen zwei Modulen und zwischen zwei Komponenten. Verweise enthalten nur die absolut nötigsten Informationen, um das Ziel aufzulösen.

Es folgt ein Beispiel für einen Verweis:

innerhalb desselben Moduls: Kopiervorlage für neue Seiten,
zwischen zwei Modulen: Glossar.

Alle Verweise auf andere Seiten derselben Dokumentation nutzen die Syntax des Xref-Makros von Antora.

Die Beschreibung der Struktur des Xref-Makros zeigt weitere, interessante Anwendungsfälle für diese Art von Verweisen.

Mehr zu Querverweisen hier.

3.1.1. Glossar

Verweise auf das Glossar dürfen nur bei der ersten Verwendung eines entsprechenden Begriffs geschehen. Alle weitere Vorkommen eines Begriffs werden aus Gründen des Leseflusses nicht mit einem Verweis hinterlegt. Es folgt ein Beispiel für den Eintrag des Backends im Glossar.

Mehr zur Verwendung des Glossars hier.

3.2. Abbildungen

Abbildung 1. Beispiel einer Abbildung

Mehr zu Abbildungen hier.

3.3. Tabellen

Tabelle 1. Beispiel einer Tabelle
Spalte 1	Spalte 2	Spalte 3	Spalte 4
Zelle 11	Zelle 12	Zelle 13	Zelle 14
Zelle 21	Zelle 22	Zelle 23	Zelle 24
Zelle 31	Zelle 32	Zelle 33	Zelle 34

Mehr zu Tabellen hier.

3.4. Listings

Listing 3. Beispiel eines Listings

public class HalloWelt {
    public static void main(String[] args) {
        System.out.println("Hallo Welt");
    }
}

Mehr zu Listings hier.

3.5. Admonition Blocks

Optionale Ergänzungen des Textes wie weiterführende Links, Dokumente, Artikel, etc.

Optionale Inhalte, die eigene Erfahrungswerte (Good / Best Practices, Tipps & Tricks, …) einbringen.

Allgemeine Vorgaben der IsyFact.

Typische Fallstricke bei der Nutzung der IsyFact.

Typische Fehler bei der Nutzung der IsyFact.

Anforderung

Anforderungen an die Entwicklung von Anwendungen und IT-Systemen.

Vorgabe

Regeln für die Architektur von Anwendungen und IT-Systemen.

Vorgabe

Regeln für die Sicherheit von IT-Systemen.

Vorgabe

Regeln zur Gestaltung von grafischen Oberflächen.

Mehr zu Admonition Blocks hier.

Mehr zu Status-Auszeichnungen der Dokumentation wie Deprecation, "in Erstellung" hier.