Admonitions

Use the three admonition types — Note, Tip, and Important — sparingly and as described here. Do not create different kinds of admonitions or vary the admonition labels.

Note

Note admonitions call out key details for the user to understand.

• Do not overuse. Too many notes is visually cluttered and defeats the point of setting off information.
• Label with Note in boldface.
• Do not set off the label with a colon or other punctuation.
• Do not use please as in Please note.

Note These guidelines currently do not define colors, iconography, or other visual formatting for admonitions.

Tip

Tip admonitions provide optional information that users might use to improve their experience.

• Use rarely.
• Label with Tip in boldface.
• Do not set off the label with a colon or other punctuation.

Tip When authoring content in DITA, set the <note> @type to tip or important. The default type is note.

Important

Important admonitions warn users to avoid actions that might have severe results such as loss of data.

• Use rarely.
• Label with Important in boldface.
• Do not set off the label with a colon or other punctuation.
• Do not use note as in Important note.

Important Do not overuse important notes or users will no longer consider them as significant.