Kennisgevingen (bijschriften, opmerkingen, waarschuwingen, enz.)

DevSite ondersteunt verschillende berichtstijlen, gepresenteerd als vakken met verschillende achtergrondkleuren. De achtergrondkleuren zijn vooraf gedefinieerd en u kunt mededelingen maken met HTML of Markdown.

Beschikbare berichttypen

Opmerking

<aside class="note">
<b>Note:</b> An ordinary note.
</aside>

Note: An ordinary note.

Tip

<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>

Tip: An ordinary tip.

Voorzichtigheid

<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>

Caution: Suggests proceeding with caution.

Waarschuwing

<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>

Warning: Stronger than caution; it means "Don't do this."

Belangrijk

<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>

Important: Defines an important concept.

Sleutelpunt

<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>

Key Point: Defines an important takeaway.

Sleutelterm

<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>

Key Term: Defines important terminology.

Objectief

<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>

Objective: Defines the goal of a procedure.

Succes

<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>

Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.

Bèta

<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>

Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.

Voorbeeld

<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>

Preview: A note or tip for a feature preview.

Hondenvoer

<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>

Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.

Afgekeurd

<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>

Deprecated: A note or tip for a deprecated feature, product, or service.

Gebruiksnotities

HTML-gebruik

We raden u aan deze klassen te gebruiken met het HTML5 <aside> -element, maar u kunt in plaats daarvan ook een ander element op blokniveau gebruiken (zoals <p> ).

De HTML-klassen bepalen de kleur en het pictogram van een mededeling, maar stellen niet automatisch het vetgedrukte eerste woord in; u moet dat woord handmatig schrijven, zoals weergegeven in de voorbeelden. In theorie zou je een ander woord kunnen gebruiken dan het woord dat overeenkomt met de klasse, maar we raden je aan om je aan de eerste woorden hierboven te houden.

In oudere documenten ziet u mogelijk class="special" of niet-standaard klassenamen in plaats van class="note" . Deze klassennamen produceren mededelingen die visueel identiek zijn aan een note , maar we raden aan om class="note" te gebruiken in plaats van speciale of niet-standaard klassennamen.

Gebruik van afwaarderingen

De Markdown-stijlen bepalen de kleur en het pictogram van een mededeling, en stellen automatisch het vetgedrukte eerste woord van de mededeling in. Zo begint een notitie in Markdown bijvoorbeeld altijd met het woord Let op: vetgedrukt.

Voor een mededeling met meer dan één alinea gebruikt u in plaats daarvan HTML <aside> (en <p> ).

Mogelijk ziet u Belangrijk: in plaats van Note: . Die Markdown-stijl produceert mededelingen die visueel identiek zijn aan een Note: mededeling.

Beste praktijken

DevSite raadt u aan de volgende best practices te volgen bij het toevoegen van mededelingen aan uw documentatie:

Aanbevolen

• Wees beknopt (probeer de mededelingen in één of twee zinnen te houden).
• Beperk kennisgevingen tot één per pagina indien mogelijk (of één per sectie indien nodig).
• Zorg ervoor dat mededelingen alleen belangrijke inhoud bevatten die u onder de aandacht wilt brengen; neem geen inhoud op in een kennisgeving waarvan u niet zeker weet wat u ermee moet doen.
• Gebruik mededelingen voordat de gebruiker de informatie nodig heeft, niet erna.

Niet aanbevolen

• Neem geen codevoorbeelden, tabellen of afbeeldingen op in mededelingen.
• Vermijd het op elkaar stapelen van mededelingen, ook al zijn ze van verschillende typen.
• Probeer geen mededelingen direct na de kopjes in te voegen.
• Gebruik geen mededelingen om vereisten vóór een procedure op te geven.

Deze best practices zijn voor het grootste deel van toepassing op mededelingen van het type note , caution en warning , maar kunnen ook op andere typen van toepassing zijn.

Goede voorbeelden

Houd het simpel:

Wees cautions met mogelijk gegevensverlies:

Gebruik warning voor mogelijk letsel:

Gebruik de juiste kennisgevingstypen voor inhoud, zoals key-term of success :

Slechte voorbeelden

Kennisgevingen mogen niet overdreven uitgebreid zijn of informatie overbrengen die tot de kerninhoud behoort:

Kennisgevingen mogen geen vereisten vóór een procedure specificeren (gebruik in plaats daarvan een sectie "Vereisten"):