Notices (callouts, notes, warnings, etc.)

DevSite supports several notice styles, presented as boxes with different background colors. The background colors are predefined, and you can create notices using either HTML or Markdown.

Available notice types

Note

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

Note: An ordinary note.

Tip

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

Tip: An ordinary tip.

Caution

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

Caution: Suggests proceeding with caution.

Warning

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

Key Point

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

Key Point: Defines an important takeaway.

Key Term

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

Key Term: Defines important terminology.

Objective

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

Objective: Defines the goal of a procedure.

Success

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

Preview

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

Deprecated

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

Usage notes

HTML usage

We recommend using these classes with the HTML5 <aside> element, but you can use another block-level element (such as <p>) instead.

The HTML classes determine the color and icon of a notice, but they don't automatically set the bolded first word; you need to write that word manually, as shown in the examples. You could theoretically use a word other than the one corresponding to the class, but we recommend that you stick with the first words shown above.

In older documents, you may see class="special" or nonstandard class names instead of class="note". Those class names produce notices that are visually identical to a note notice, but we recommend using class="note" instead of special or nonstandard class names.

Markdown usage

The Markdown styles determine the color and icon of a notice, and they automatically set the bolded first word of the notice. So, for example, a note in Markdown always starts with the word Note: in bold.

For a notice with more than one paragraph, use HTML <aside> (and <p>) instead.

You may see Important: instead of Note:. That Markdown style produces notices that are visually identical to a Note: notice.

Best practices

DevSite recommends that you adhere to the following best practices when adding notices to your documentation:

Recommended

• Be succinct (try to keep notices to one or two sentences).
• Limit notices to one per page if possible (or one per section if necessary).
• Ensure that notices contain only important content that you want to highlight; don't include content in a notice that you're just not sure what to do with.
• Use notices before the user needs the information, not after.

Not Recommended

• Don't include code examples, tables, or images in notices.
• Avoid stacking notices on top of each other, even if they are of different types.
• Try not to insert notices immediately after headings.
• Don't use notices to specify prerequisites before a procedure.

For the most part, these best practices apply to notices of type note, caution, and warning, but can apply to other types.

Good examples

Keep it simple:

Use cautions for potential loss of data:

Use warning for potential injury:

Use appropriate notice types for content, such as key-term or success:

Bad examples

Notices should not be overly verbose or convey information that belongs in the core content:

Notices should not specify prerequisites before a procedure (use a "Prerequisites" section instead):