Avis (accroches, remarques, avertissements, etc.)

DevSite accepte plusieurs styles de notifications, présentés sous forme de cases avec différentes couleurs d'arrière-plan. Les couleurs d'arrière-plan sont prédéfinies, et vous pouvez créer des notifications en HTML ou en Markdown.

Types de notifications disponibles

Remarque

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

Note: An ordinary note.

Conseil

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

Tip: An ordinary tip.

Attention

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

Caution: Suggests proceeding with caution.

Avertissement

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

Important

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

Important: Defines an important concept.

Point essentiel

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

Key Point: Defines an important takeaway.

Terme clé

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

Key Term: Defines important terminology.

Objectif

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

Objective: Defines the goal of a procedure.

Opération réussie

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

Aperçu

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

Preview: A note or tip for a feature preview.

Dogfood

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

Obsolète

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

Remarques sur l'utilisation

Utilisation du code HTML

Nous vous recommandons d'utiliser ces classes avec l'élément <aside> HTML5, mais vous pouvez utiliser un autre élément de niveau bloc (tel que <p>) à la place.

Les classes HTML déterminent la couleur et l'icône d'une notification, mais elles ne définissent pas automatiquement le premier mot en gras. Vous devez écrire ce mot manuellement, comme indiqué dans les exemples. Vous pouvez théoriquement utiliser un autre mot que celui correspondant à la classe, mais nous vous recommandons de vous en tenir aux premiers mots indiqués ci-dessus.

Dans les documents plus anciens, vous pouvez voir class="special" ou des noms de classe non standards au lieu de class="note". Ces noms de classe génèrent des notifications visuellement identiques à celles de note, mais nous vous recommandons d'utiliser class="note" plutôt que des noms de classe spéciaux ou non standards.

Utilisation de Markdown

Les styles Markdown déterminent la couleur et l'icône d'un avis, et ils définissent automatiquement le premier mot de l'avis en gras. Par exemple, une note en Markdown commence toujours par le mot "Remarque :" en gras.

Pour une notification comportant plusieurs paragraphes, utilisez plutôt le code HTML <aside> (et <p>).

Il est possible que le message "Important :" s'affiche à la place de Note:. Ce style Markdown produit des notifications visuellement identiques à une notification Note:.

Bonnes pratiques

DevSite vous recommande de respecter les bonnes pratiques suivantes lorsque vous ajoutez des avis à votre documentation:

Recommandé

• Soyez concis (essayez de limiter les notifications à une ou deux phrases).
• Si possible, limitez les avis à un par page (ou un par section si nécessaire).
• Assurez-vous que les notifications ne contiennent que du contenu important que vous souhaitez mettre en avant. N'incluez pas de contenu dans une notification dont vous ne savez pas quoi faire.
• Utilisez des notifications avant que l'utilisateur n'ait besoin des informations, et non après.

Non recommandé

• N'incluez pas d'exemples de code, de tableaux ni d'images dans les notifications.
• Évitez d'empiler des notifications les unes sur les autres, même si elles sont de différents types.
• Essayez de ne pas insérer de notifications immédiatement après les titres.
• N'utilisez pas de notifications pour spécifier les conditions préalables avant une procédure.

Dans la plupart des cas, ces bonnes pratiques s'appliquent aux notifications de type note, caution et warning, mais peuvent s'appliquer à d'autres types.

À faire

Faites simple :

Utilisez cautions en cas de perte de données potentielle:

Utilisez warning pour les blessures potentielles:

Utilisez les types de notifications appropriés pour le contenu, tels que key-term ou success:

À ne pas faire

Les notifications ne doivent pas être trop longues ni contenir des informations qui appartiennent au contenu principal:

Les avis ne doivent pas spécifier de conditions préalables avant une procédure (utilisez plutôt une section "Conditions préalables"):