Avisos (avisos, notes, advertències, etc.)

DevSite admet diversos estils d'avís, presentats com a caixes amb diferents colors de fons. Els colors de fons estan predefinits i podeu crear avisos mitjançant HTML o Markdown.

Tipus d'avís disponibles

Nota

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

Note: An ordinary note.

Consell

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

Tip: An ordinary tip.

Precaució

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

Caution: Suggests proceeding with caution.

Avís

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

Punt clau

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

Key Point: Defines an important takeaway.

Terme clau

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

Key Term: Defines important terminology.

Objectiu

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

Objective: Defines the goal of a procedure.

Èxit

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

Beta

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

Vista prèvia

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

Preview: A note or tip for a feature preview.

Experiència interna

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

Obsolet

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

Notes d'ús

Ús HTML

Us recomanem que utilitzeu aquestes classes amb l'element HTML5 <aside> , però podeu utilitzar un altre element a nivell de bloc (com ara <p> ).

Les classes HTML determinen el color i la icona d'un avís, però no estableixen automàticament la primera paraula en negreta; cal escriure aquesta paraula manualment, tal com es mostra als exemples. Teòricament podríeu utilitzar una paraula diferent de la corresponent a la classe, però us recomanem que us quedeu amb les primeres paraules que es mostren més amunt.

En documents antics, podeu veure noms de classes class="special" o no estàndard en lloc de class="note" . Aquests noms de classe produeixen avisos que són visualment idèntics a un avís note , però recomanem que utilitzeu class="note" en comptes de noms de classe especials o no estàndard.

Ús de rebaixa

Els estils Markdown determinen el color i la icona d'un avís i estableixen automàticament la primera paraula en negreta de l'avís. Així, per exemple, una nota a Markdown sempre comença amb la paraula Nota: en negreta.

Per a un avís amb més d'un paràgraf, utilitzeu HTML <aside> (i <p> ​​).

És possible que vegeu Important: en lloc de Note: . Aquest estil Markdown produeix avisos que són visualment idèntics a un Note: :.

Bones pràctiques

DevSite recomana que seguiu les pràctiques recomanades següents quan afegiu avisos a la documentació:

Recomanat

• Sigueu concis (intenta mantenir els avisos d'una o dues frases).
• Limiteu els avisos a un per pàgina si és possible (o un per secció si cal).
• Assegureu-vos que els avisos només continguin contingut important que vulgueu destacar; no inclogueu contingut en un avís amb el qual no esteu segur de què fer.
• Utilitzeu els avisos abans que l'usuari necessiti la informació, no després.

No recomanat

• No inclogueu exemples de codi, taules o imatges als avisos.
• Eviteu apilar els avisos uns sobre els altres, encara que siguin de tipus diferent.
• Intenteu no inserir avisos immediatament després dels encapçalaments.
• No utilitzeu avisos per especificar requisits previs abans d'un procediment.

En la seva majoria, aquestes pràctiques recomanades s'apliquen als avisos de tipus note , caution i warning , però es poden aplicar a altres tipus.

Bons exemples

Feu-ho senzill:

Aneu cautions davant la possible pèrdua de dades:

Utilitzeu warning per a possibles lesions:

Utilitzeu els tipus d'avís adequats per al contingut, com ara key-term o success :

Mals exemples

Els avisos no han de ser massa detallats ni transmetre informació que pertanyi al contingut bàsic:

Els avisos no haurien d'especificar requisits previs abans d'un procediment (utilitzeu una secció "Requisits previs"):