Avvisi (callout, note, avvisi e così via)

DevSite supporta diversi stili di avviso, presentati come riquadri con colori di sfondo diversi. I colori di sfondo sono predefiniti e puoi creare avvisi utilizzando HTML o Markdown.

Tipi di comunicazioni disponibili

Nota

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

Note: An ordinary note.

Suggerimento

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

Tip: An ordinary tip.

Attenzione

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

Caution: Suggests proceeding with caution.

Avviso

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

Importante

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

Important: Defines an important concept.

Punto chiave

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

Key Point: Defines an important takeaway.

Termine chiave

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

Key Term: Defines important terminology.

Obiettivo

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

Objective: Defines the goal of a procedure.

Operazione riuscita

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

Anteprima

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

Preview: A note or tip for a feature preview.

Versione sperimentale

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

Deprecato

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

Note sull'utilizzo

Utilizzo di HTML

Ti consigliamo di utilizzare queste classi con l'elemento <aside> HTML5, ma puoi utilizzare un altro elemento a livello di blocco (ad esempio <p>).

Le classi HTML determinano il colore e l'icona di una notifica, ma non impostano automaticamente la prima parola in grassetto; devi scrivere questa parola manualmente, come mostrato negli esempi. In teoria, potresti utilizzare una parola diversa da quella corrispondente alla classe, ma ti consigliamo di attenerti alle prime parole mostrate sopra.

Nei documenti precedenti, potresti vedere class="special" o nomi di classi non standard anziché class="note". Questi nomi di classe producono notifiche visivamente identiche a una notifica note, ma consigliamo di utilizzare class="note" anziché nomi di classe speciali o non standard.

Utilizzo di Markdown

Gli stili Markdown determinano il colore e l'icona di una notifica e impostano automaticamente la prima parola in grassetto della notifica. Ad esempio, una nota in Markdown inizia sempre con la parola Nota: in grassetto.

Per una notifica con più di un paragrafo, utilizza invece <aside> (e <p>) HTML.

Potresti vedere Importante: anziché Note:. Questo stile Markdown genera avvisi visivamente identici a un avviso Note:.

Best practice

DevSite consiglia di rispettare le seguenti best practice quando aggiungi avvisi alla documentazione:

Consigliato

• Sii conciso (cerca di limitare le notifiche a una o due frasi).
• Se possibile, limita le notifiche a una per pagina (o una per sezione, se necessario).
• Assicurati che le notifiche contengano solo contenuti importanti che vuoi mettere in evidenza. Non includere contenuti in una notifica di cui non sai cosa fare.
• Utilizza le notifiche prima che l'utente abbia bisogno delle informazioni, non dopo.

Non consigliato

• Non includere esempi di codice, tabelle o immagini nelle notifiche.
• Evita di sovrapporre le notifiche, anche se sono di tipi diversi.
• Cerca di non inserire le notifiche subito dopo le intestazioni.
• Non utilizzare le notifiche per specificare i prerequisiti prima di una procedura.

Per la maggior parte, queste best practice si applicano alle notifiche di tipo note, caution e warning, ma possono essere applicate anche ad altri tipi.

Esempi giusti

Scegli la semplicità:

Utilizza cautions per la potenziale perdita di dati:

Utilizza warning per potenziali lesioni:

Utilizza tipi di avviso appropriati per i contenuti, ad esempio key-term o success:

Esempi sbagliati

Le notifiche non devono essere eccessivamente verbose o trasmettere informazioni che appartengono ai contenuti principali:

Le notifiche non devono specificare i prerequisiti prima di una procedura (utilizza invece una sezione "Prerequisiti"):