Avisos (textos destacados, notas, advertencias, etcétera)

DevSite admite varios estilos de avisos, que se presentan como cuadros con diferentes colores de fondo. Los colores de fondo están predefinidos, y puedes crear avisos con HTML o Markdown.

Tipos de avisos disponibles

Nota

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

Note: An ordinary note.

Sugerencia

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

Tip: An ordinary tip.

Precaución

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

Caution: Suggests proceeding with caution.

Advertencia

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

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

Key Point: Defines an important takeaway.

Término clave

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

Listo

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

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

Preview: A note or tip for a feature preview.

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

Obsoleto

<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

Te recomendamos que uses estas clases con el elemento <aside> de HTML5, pero puedes usar otro elemento a nivel de bloque (como <p>).

Las clases HTML determinan el color y el ícono de un aviso, pero no establecen automáticamente la primera palabra en negrita. Debes escribir esa palabra de forma manual, como se muestra en los ejemplos. En teoría, podrías usar una palabra que no sea la que corresponde a la clase, pero te recomendamos que uses las primeras palabras que se muestran arriba.

En documentos más antiguos, es posible que veas class="special" o nombres de clases no estándar en lugar de class="note". Esos nombres de clase producen avisos que son visualmente idénticos a los de note, pero recomendamos usar class="note" en lugar de nombres de clase especiales o no estándares.

Uso de Markdown

Los estilos de Markdown determinan el color y el ícono de un aviso, y establecen automáticamente la primera palabra en negrita del aviso. Por ejemplo, una nota en Markdown siempre comienza con la palabra Nota: en negrita.

Para un aviso con más de un párrafo, usa <aside> (y <p>) en su lugar.

Es posible que veas Importante: en lugar de Note:. Ese estilo de Markdown produce avisos que son visualmente idénticos a los de Note:.

Prácticas recomendadas

DevSite recomienda que sigas las siguientes prácticas recomendadas cuando agregues avisos a tu documentación:

Recomendado

• Sé breve (intenta que los avisos tengan una o dos oraciones).
• Si es posible, limita los avisos a uno por página (o uno por sección si es necesario).
• Asegúrate de que los avisos contengan solo el contenido importante que deseas destacar. No incluyas contenido en un aviso con el que no sepas qué hacer.
• Usa avisos antes de que el usuario necesite la información, no después.

No recomendada

• No incluyas ejemplos de código, tablas ni imágenes en los avisos.
• Evita apilar avisos uno sobre otro, incluso si son de diferentes tipos.
• Intenta no insertar avisos inmediatamente después de los encabezados.
• No uses avisos para especificar requisitos previos antes de un procedimiento.

En general, estas prácticas recomendadas se aplican a los avisos de tipo note, caution y warning, pero también pueden aplicarse a otros tipos.

Ejemplos que debe seguir

No te compliques:

Usa cautions para la posible pérdida de datos:

Usa warning para posibles lesiones:

Usa los tipos de avisos adecuados para el contenido, como key-term o success:

Ejemplos que debe evitar

Los avisos no deben ser demasiado extensos ni transmitir información que pertenezca al contenido principal:

Los avisos no deben especificar requisitos previos antes de un procedimiento (en su lugar, usa una sección "Requisitos previos"):