Änderungen an Inhalten
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.
Der Leitfaden bietet die Möglichkeit an, Änderungen an Inhalten über vordefinierte Elemente auszuzeichnen. Er unterstützt die Auszeichnung von Inhalten in Erstellung, in Überarbeitung und in Deprecation.
| Nachdem eine Änderung abgeschlossen ist, muss die Auszeichnung an allen betreffenden Stellen entfernt werden. |
1. Inhalte in Erstellung
Wenn Inhalte neu erstellt werden, geschieht dies meist über einen längeren Zeitraum hinweg. Während der Erstellung sind diese neuen Inhalte in der Regel noch nicht in der ganzen IsyFact berücksichtigt.
Um solche Inhalte auszuzeichnen, bietet der Leitfaden eine allgemeine Variante, eine für Seiten und eine für Bausteine an. Es sollte immer die Variante gewählt werden, die am besten zum Wirkungsbereich (Scope) der Änderung passt.
1.1. Allgemeiner Hinweis
Dieser Hinweis kann an beliebigen Stellen im Text platziert werden. Es empfiehlt sich, ihn direkt nach einer Überschrift zu platzieren.
Markup:
include::documentation-guide::partial$content-new.adoc[]Ergebnis:
1.2. Hinweis für Seiten
Dieser Hinweis sollte, direkt nach dem Lizenzhinweis, als erster Inhalt auf einer Seite stehen.
Markup:
include::documentation-guide::partial$content-new-page.adoc[]Ergebnis:
1.3. Hinweis für Bausteine
Dieser Hinweis sollte auf allen Seiten des Bausteins platziert werden.
Markup:
include::documentation-guide::partial$content-new-building-block.adoc[]Ergebnis:
2. Inhalte in Überarbeitung
Von Zeit zu Zeit werden Inhalte aus diversen Gründen grundlegend überarbeitet. Während der Überarbeitung sind diese Inhalte möglicherweise inkonsistent, sowohl in sich als auch zum Rest der IsyFact.
Um solche Inhalte auszuzeichnen, bietet der Leitfaden eine allgemeine Variante, eine für Seiten und eine für Bausteine an. Es sollte immer die Variante gewählt werden, die am besten zum Wirkungsbereich (Scope) der Änderung passt.
2.1. Allgemeiner Hinweis
Dieser Hinweis kann an beliebigen Stellen im Text platziert werden. Es empfiehlt sich, ihn direkt nach einer Überschrift zu platzieren.
Markup:
include::documentation-guide::partial$content-revised.adoc[]Ergebnis:
2.2. Hinweis für Seiten
Dieser Hinweis sollte, direkt nach dem Lizenzhinweis, als erster Inhalt auf einer Seite stehen.
Markup:
include::documentation-guide::partial$content-revised-page.adoc[]Ergebnis:
2.3. Hinweis für Bausteine
Dieser Hinweis sollte auf allen Seiten des Bausteins platziert werden.
Markup:
include::documentation-guide::partial$content-revised-building-block.adoc[]Ergebnis:
3. Inhalte in Deprecation
Gelegentlich veralten Bausteine und ihre Dokumentation. In der Dokumentationsseite werden Bausteine, die deprecated sind – die demnach in einer späteren Version entfallen können – als Deprecation ausgezeichnet.
3.1. Hinweis für Baustein
Dieser Hinweis sollte auf allen Seiten des mit Deprecation auszuzeichnenden Bausteins platziert werden.
Ein vorbereiteter Text mit Icon aus isy-documentation wird inkludiert.
Wird ein Baustein abgelöst, ist zusätzlich ein Verweis auf den neuen Baustein angebracht.
Markup:
include::documentation-guide::partial$content-deprecated-building-block.adoc[]Ergebnis:
3.2. Allgemeiner Hinweis
Zur Auszeichnung einer Deprecation an einem beliebigen Abschnitt (z.B. Kapitel) einer Dokumentationsseite kann auf folgende Auszeichnung zurückgegriffen werden.
Ein vorbereiteter Text mit Icon aus isy-documentation wird damit inkludiert.
|
Dabei sollte die Auszeichnung direkt unterhalb einer Überschrift platziert werden, damit der Abschnitt inklusive untergeordneter Abschnitte tieferer Ebenen bis zur nächsten Überschrift der gleichen Ebene als deprecated erkennbar ist. Beachte, dass durch die Auszeichnung das Ende des Deprecation Abschnitts nicht explizit dargestellt werden kann. |
Markup:
include::documentation-guide::partial$content-deprecated.adoc[]Ergebnis:
3.3. (Optional) Verweis auf neue Dokumentationsseite
Die Deprecation Markierung für einen Baustein oder Abschnitt kann optional um einen jeweils fest definierten Zusatztext und selbst definierten Verweis auf die neue Dokumentationsseite erweitert werden. Dafür ist ein Attribut mit dem entsprechenden Verweis vor der Inkludierung des Deprecation-Bausteins oder -Abschnitts einzufügen. Dieser Verweis kann im Verlauf der Dokumentationsseite geändert werden, wenn es mehrere Deprecation-Abschnitte mit unterschiedlichen Verweisen gibt.
Markup:
:linkaktuell: xref:<Antora-Pfad zur neuen Seite>.adoc[]
include::documentation-guide::partial$content-deprecated-building-block.adoc[]Ergebnis: