DevSite unterstützt mehrere Hinweisstile, die als Felder mit unterschiedlichen Hintergrundfarben dargestellt werden. Die Hintergrundfarben sind vordefiniert und Sie können Benachrichtigungen entweder in HTML oder Markdown erstellen.
Verfügbare Arten von Hinweisen
Hinweis
HTML
<aside class="note">
<b>Note:</b> An ordinary note.
</aside>
Markdown
Note: An ordinary note.
Tipp
HTML
<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>
Markdown
Tip: An ordinary tip.
Achtung
HTML
<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>
Markdown
Caution: Suggests proceeding with caution.
Warnung
HTML
<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>
Markdown
Warning: Stronger than caution; it means "Don't do this."
Wichtig
HTML
<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>
Markdown
Important: Defines an important concept.
Wichtiger Punkt
HTML
<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>
Markdown
Key Point: Defines an important takeaway.
Schlüsselbegriff
HTML
<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>
Markdown
Key Term: Defines important terminology.
Ziel
HTML
<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>
Markdown
Objective: Defines the goal of a procedure.
Erfolg
HTML
<aside class="success">
<b>Success:</b> Describes a successful action or an error-free status.
Used only in interactive or dynamic content; don't use in ordinary
static pages.
</aside>
Markdown
Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.
Beta
HTML
<aside class="beta">
<b>Beta:</b> A notice that describes a beta-release feature, which is
subject to change or removal in new minor versions of the product.
</aside>
Markdown
Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.
Vorschau
HTML
<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>
Markdown
Preview: A note or tip for a feature preview.
Dogfood
HTML
<aside class="dogfood">
<b>Dogfood:</b> A notice that applies only temporarily, during internal
dogfood testing. Remove all Dogfood notices before making a document
publicly visible.
</aside>
Markdown
Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.
Verworfen
HTML
<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>
Markdown
Deprecated: A note or tip for a deprecated feature, product, or service.
Verwendungshinweise
HTML-Nutzung
Wir empfehlen, diese Klassen mit dem HTML5-Element <aside> zu verwenden. Sie können aber auch ein anderes Blockebenen-Element (z. B. <p>) verwenden.
Die HTML-Klassen bestimmen die Farbe und das Symbol einer Benachrichtigung, aber sie setzen nicht automatisch das erste Wort fett. Sie müssen dieses Wort wie in den Beispielen gezeigt manuell eingeben. Theoretisch können Sie auch ein anderes Wort als das der Klasse verwenden. Wir empfehlen jedoch, sich an die ersten Wörter oben zu halten.
In älteren Dokumenten wird anstelle von class="note" möglicherweise class="special" oder ein nicht standardmäßiger Klassenname angezeigt. Diese Klassennamen führen zu Benachrichtigungen, die optisch mit einer note-Benachrichtigung identisch sind. Wir empfehlen jedoch, class="note" anstelle von speziellen oder nicht standardmäßigen Klassennamen zu verwenden.
Markdown verwenden
Die Markdown-Stile bestimmen die Farbe und das Symbol einer Mitteilung und setzen automatisch das erste Wort der Mitteilung fett. So beginnt eine Notiz in Markdown immer mit dem fett formatierten Wort „Hinweis:“.
Verwenden Sie für eine Mitteilung mit mehreren Absätzen stattdessen HTML <aside> (und <p>).
Möglicherweise wird anstelle von Note: „Wichtig:“ angezeigt. Mit diesem Markdown-Stil werden Hinweise generiert, die optisch mit einer Note:-Mitteilung identisch sind.
Best Practices
DevSite empfiehlt, die folgenden Best Practices zu beachten, wenn Sie Ihrer Dokumentation Hinweise hinzufügen:
Empfohlen
- Seien Sie prägnant. Versuchen Sie, Benachrichtigungen auf ein oder zwei Sätze zu beschränken.
- Beschränken Sie die Hinweise nach Möglichkeit auf einen pro Seite (oder bei Bedarf auf einen pro Bereich).
- Achten Sie darauf, dass Hinweise nur wichtige Inhalte enthalten, die Sie hervorheben möchten. Fügen Sie keine Inhalte in einen Hinweis ein, mit denen Sie nicht sicher sind, was Sie damit tun sollen.
- Verwenden Sie Hinweise, bevor der Nutzer die Informationen benötigt, nicht danach.
Nicht empfohlen
- Fügen Sie in Mitteilungen keine Codebeispiele, Tabellen oder Bilder ein.
- Vermeiden Sie es, Benachrichtigungen übereinander zu stapeln, auch wenn sie unterschiedlicher Art sind.
- Fügen Sie Hinweise nicht direkt nach Überschriften ein.
- Verwenden Sie keine Hinweise, um Voraussetzungen vor einem Vorgang anzugeben.
Diese Best Practices gelten in erster Linie für Mitteilungen vom Typ note, caution und warning, können aber auch für andere Typen gelten.
Beispiele für gute Texte
Weniger ist mehr:
Verwenden Sie cautions für einen möglichen Datenverlust:
Verwenden Sie warning für potenzielle Verletzungen:
Verwenden Sie für Inhalte die entsprechenden Arten von Hinweisen, z. B. key-term oder success:
Beispiele für schlechte Texte
Hinweise dürfen nicht zu ausschweifend sein oder Informationen enthalten, die zum Hauptinhalt gehören:
In Hinweisen dürfen keine Voraussetzungen für eine Prozedur angegeben werden. Verwenden Sie stattdessen einen Abschnitt „Voraussetzungen“: