Zum Hauptinhalt springen

Nutzung der Dokumentation

Struktur​

Allgemein​

Die Dokumentation ist entlang der FIM-Bausteine strukturiert.

Wo finde ich was?​

Markierungen​

Neben der textuellen Beschreibung finden Sie in der Dokumentation wiederkehrende Elemente, die Ihnen die das Verständnis verbessern und den Einstieg erleichtern sollen.

SymbolBedeutung
⚠️Besonders wichtige Informationen
✔️Positive Beispiele
❌Negative Beispiele
🆕Neue Elemente in FIM (bspw. im technischen Standard)

Nutzung von Badges​

ab XZuFi 2.3
ab XDF 3
ab XProzess 3

NEU Badges sollten möglichst vor dem Text platziert werden.
Badges können auch im Text SDG verwendet werden, um auf bestimmte Versionen oder Anforderungen hinzuweisen.

Verwendung von Markierungen in Überschriften ⭐​

Werden Markierungen in Überschriften verwendet, werden diese auch in Sidebars angezeigt.

Verwendung von Markierungen in Texten​

:heavy_exclamation_mark: Sollen Markierungen nur am Anfang, nur am Ende oder an beliebiger Stelle in Texten verwendet werden?

Code-Beispiele​

<xzufi:referenzLeiKa listURI="urn:de:fim:leika:leistung" listVersionID="20220301">
  <code>99003057001000</code>
</xzufi:referenzLeiKa>

Infoboxen (Admonitions)​

Es gibt verschiedene Infoboxen, mit denen Artikel strukturiert werden können. Diese sollten artikelübergreifend ein einheitliches Erscheinungsbild bieten, indem die Boxen immer in ähnlichen Situationen verwendet werden. Die Überschriften der Boxen sollen möglichst gleichbleibend genutzt werden, können aber auch nach Bedarf variiert werden.

Für eine übersichtliche Gestaltung sollte innerhalb der Boxen auf komplexere Strukturen wie mehrere Reiter verzichtet werden.

Detailboxen

Detailboxen sind ausklappbare Boxen, die genutzt werden, um Zusatzinformationen unterzubringen. Sie enthalten beispielsweise lange Listen und Tabellen, die bei Bedarf angesehen werden können.

Allgemeine Infos

Die blaue Info-Box wird am Anfang eines Artikels genutzt, um eine Zusammenfassung der wichtigsten Informationen zum Artikel zu geben, ohne diese inhaltlich zu vertiefen.

Weiterführende Informationen

Die blaue Info-Box kann ebenfalls innerhalb eines Artikels genutzt werden, um Zusatzinformationen darzustellen oder um auf weitere Abschnitte der Dokumentation oder auf externe Informationsquellen zu verweisen, mit denen die Inhalte des Artikels vertieft werden können.

Redaktioneller Hinweis

Die weiße Hinweis-Box kann verwendet werden, um auf technische oder redaktionelle Hintergründe des Artikels aufmerksam zu machen. Hier kann beispielsweise darauf hingewiesen werden, dass ein Artikel umzieht oder sich noch im Aufbau befindet.

Praxis-Tipp

In der grünen Tipp-Box finden sich Hinweise, die sich in der praktischen Arbeit als hilfreich erwiesen haben. Hier können beispielsweise Links zu Arbeitsmaterialien wie Codelisten untergebracht werden.

Merke

Die gelbe Merke-Box soll am Ende eines langen Artikels einen abschließenden Überblick geben. Hier sind die wichtigsten Punkte kurz und knapp zusammengefasst.

Achtung

In der roten Achtung-Box finden sich Hinweise zu möglichen Fehlerquellen, die bei der Arbeit beachtet werden müssen. Hier kann auf häufige Probleme, Missverständnisse oder Wortdopplungen hingewiesen werden.

Attribute​

Die Attribute unterscheiden sich durch ihre Charakteristik. Diese Unterschiede werden auch optisch in den Übersichten deutlich gemacht:

  • Schlüsselattribute*
    • Ein Schlüsselattribut identifiziert das FIM-Element eindeutig.
    • Kennzeichnung: *
    • Alle Schlüsselattribute sind auch Pflichtattribute
  • Pflichtattribute
    • Ein Pflichtattribut muss zu jedem FIM-Element angeben werden
    • Kennzeichnung: fette Schreibweise
  • Optionale Attribute
    • Ein optionales Attribut muss nicht zwangsläufig zu einem FIM-Element angegeben werden bzw. kann im Rahmen einer späteren Nachpflege gefüllt werden.
    • Kennzeichnung: kursive Schreibweise
  • Automatisch befüllte Attribute
    • Diese Attribute sollten direkt vom Software-System nach vorgegebener Logik befüllt werden und nicht durch die Nutzer editierbar sein.
    • Kennzeichnung: unterstrichen

Um die Vielzahl der Attribute übersichtlicher zu gestalten, werden diese in verschiedene Kategorien gruppiert. Die Kategorien Identifikationsangaben und Zustandsangaben kommen in jedem FIM-Element vor. Darüber hinaus werden aber auch weitere Kategorien hinzugefügt.