Warnhinweise

(Auszug aus "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" von Thomas Schraitle)

Warnhinweise setzen Sie überall dort ein, wo Sie den Leser auf etwas aufmerksam machen möchten. Daher werden sie als Block formatiert und häufig mit einer Grafik dargestellt.

DocBook kennt fünf verschiedene Warnhinweise: caution, important, note, tip und warning. DocBook selbst legt keine besondere Semantik zugrunde, in manchen Dokumentationen ist dies jedoch streng festgelegt, teilweise sogar vorgeschrieben durch Gesetzgeber oder Normen (wie ANSI Z536.6). Denken Sie nur an das strenge Produkthaftungsgesetz in den USA. Daher sollten Sie sich nicht nur aus Konsistenz- sondern auch aus rechtlichen Gründen vorher genau überlegen, welche Semantik die einzelnen Elementnamen für Ihr Dokument haben. Eine mögliche Definition der Warnhinweise könnte wie folgt aussehen:

tip (Vorschlag)

Tipps geben dem Leser Vorschläge, sind für den eigentlichen Ablauf nicht essentiell und können daher gefahrlos ignoriert werden.

note (Hinweis)

Ein allgemeiner Hinweis, der den Leser auf mögliche Fehlerquellen hinweist.

important (Wichtig)

Ein wichtiger Hinweis, der den Leser auf Gefahrenquellen aufmerksam macht.

warning (Warnung)

Eine Warnung, die bei Nichtbeachtung eine Person schädigt oder verletzt.

caution (Gefahr, Achtung)

Eine Warnung, die bei Nichtbeachtung zum Tode führt.

Sie können jedoch auch einen anderen "Schweregrad" definieren. Falls in Ihren Dokumenten keine unmittelbar tödliche Gefahr lauert (Sie schreiben beispielsweise über Klopapier), ist ein caution sicherlich unangebracht. Wie Warnhinweise aussehen, zeigt das folgende Beispiel.

Beispiel: Einige Möglichkeiten für Warnhinweise

<tip>    
   <title>Verkürzen des Schreibaufwands bei leeren Elementen</title>    
   <para>Leere Elemente können Sie in XML auch als <tag class="emptytag">foo</tag> schreiben.</para>    
</tip>
<warning>    
   <title>Hammer und Zeh vertragen sich nicht!</title>    
   <para>Wenn Sie einen Hammer auf den großen Zeh fallen lassen, erzeugt das große Schmerzen und Beschwerden. ...</para>    
   <para>Tragen Sie ausreichend gepolsterte Schuhe, um diese Art von Unfällen zu vermeiden.</para>    
</warning>

Innerhalb eines Warnhinweises sind fast beliebige Elemente erlaubt (bis auf einen Warnhinweis innerhalb eines Warnhinweises). Wie schon oben erwähnt, diktieren verschiedene Normen wie ANSI Z536.6 einen bestimmten Aufbau:

  • Ein Titel, der die Gefahr nennt
  • Was passiert, wenn jemand eine Warnung nicht beachtet
  • Eine Lösung zur Vermeidung der Folgen

Im obigen Beispiel wurde dieses Prinzip bereits angewendet.

Weitere Informationen zum ANSI Z536.6 Standard erhalten Sie in Zehn Fragen zu ANSI Z536.6, tekom (Technische Kommunikation), Heft 2/2007, ISSN: 1436-1809.

  

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema DocBook bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2009 Millin Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

Millin Verlag, Siebengebirgsring 36, 53797 Lohmar, info(at)millin.de