Avisos (chamadas, notas, avisos etc.)

O DevSite oferece suporte a vários estilos de aviso, apresentados como caixas com cores de plano de fundo diferentes. As cores de plano de fundo são predefinidas, e você pode criar avisos usando HTML ou Markdown.

Tipos de aviso disponíveis

Observação

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

Note: An ordinary note.

Dica

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

Tip: An ordinary tip.

Cuidado

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

Caution: Suggests proceeding with caution.

Aviso

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

Ponto-chave

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

Key Point: Defines an important takeaway.

Termo-chave

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

Key Term: Defines important terminology.

Objetivo

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

Objective: Defines the goal of a procedure.

Sucesso

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

Visualizar

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

Descontinuado

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

Notas de uso

Uso de HTML

Recomendamos o uso dessas classes com o elemento <aside> do HTML5, mas você pode usar outro elemento no nível do bloco, como <p>.

As classes HTML determinam a cor e o ícone de um aviso, mas não definem automaticamente a primeira palavra em negrito. Você precisa escrever essa palavra manualmente, conforme mostrado nos exemplos. Teoricamente, é possível usar uma palavra diferente da que corresponde à classe, mas recomendamos que você use as primeiras palavras mostradas acima.

Em documentos mais antigos, você pode encontrar class="special" ou nomes de classe não padrão em vez de class="note". Esses nomes de classe produzem avisos visualmente idênticos a um aviso note, mas recomendamos o uso de class="note" em vez de nomes de classe especiais ou não padrão.

Uso do Markdown

Os estilos Markdown determinam a cor e o ícone de um aviso e definem automaticamente a primeira palavra em negrito do aviso. Por exemplo, uma nota em Markdown sempre começa com a palavra "Observação:" em negrito.

Para um aviso com mais de um parágrafo, use HTML <aside> (e <p>).

Você pode ver "Importante:" em vez de Note:. Esse estilo de Markdown produz avisos visualmente idênticos a um aviso Note:.

Práticas recomendadas

O DevSite recomenda que você siga as práticas recomendadas abaixo ao adicionar avisos à sua documentação:

Recomendado

• Seja sucinto (tente manter os avisos em uma ou duas frases).
• Limite os avisos a um por página, se possível, ou um por seção, se necessário.
• Os avisos devem conter apenas conteúdo importante que você quer destacar. Não inclua conteúdo em um aviso que você não sabe o que fazer.
• Use avisos antes que o usuário precise das informações, não depois.

Não recomendado

• Não inclua exemplos de código, tabelas ou imagens nos avisos.
• Evite empilhar avisos uns sobre os outros, mesmo que sejam de tipos diferentes.
• Evite inserir avisos imediatamente após os títulos.
• Não use avisos para especificar pré-requisitos antes de um procedimento.

Na maioria das vezes, essas práticas recomendadas se aplicam a avisos do tipo note, caution e warning, mas podem ser usadas em outros tipos.

Bons exemplos

Mantenha a simplicidade:

Use cautions para possíveis perdas de dados:

Use warning para possíveis lesões:

Use os tipos de aviso adequados para o conteúdo, como key-term ou success:

Maus exemplos

Os avisos não podem ser muito longos nem transmitir informações que pertencem ao conteúdo principal:

Os avisos não devem especificar pré-requisitos antes de um procedimento (use uma seção "Pré-requisitos"):