Notes and information boxes
Use information box or paragraph to bring attention to a piece of information.
Use your own judgment to decide which type of information box is most appropriate for the context. The following table provides a guide to the most common purposes.
| Admonition | Severity | Description | Example admonition |
|---|---|---|---|
| Warning | High | Use Warning if the information or task could result in irretrievable data loss. Also include a suggestion to back up the data they might lose. | Warning: The following task overwrites several files in your Project folder. These cannot be restored after Unity overwrites them. Before you start this task, back up any files you do not want to lose. |
| Caution | High | Use Caution if the information or task could result in retrievable data loss. If possible, include a suggestion to back up the data they might lose, and guidance on how to retrieve any data they do lose. | Caution: The following task deletes several files from your Project folder. Before you start this task, back up any files you do not want to lose. If you need to restore files later, you can do so from [...]. |
| Important | Medium | Use Important if the information or task does not carry a danger of data loss, but does have some other consequence that is not immediately obvious, such as future code rewrites. If possible, include guidance on how to prevent this consequence. | Important: When you change the properties of a prefab, Unity automatically updates the other instances of that prefab in the Scene. If you do not want this to happen, [...]. |
| Note | Medium | Use Note to provide peripheral information that the user should be aware of, but which does not put any part of their project at risk. Only place information in a Note if it contains something that you want to highlight or emphasize. In other cases, consider whether you can integrate the information into the main text. | Note: Unity supports Android 4.4 and later versions. |
| Tip | Low | Use Tip to offer advice that helps the reader optimize their work or workflow. | Tip: To edit all Rigidbody components at once, select all GameObjects that contain one, and use the Rigidbody Inspector to apply the same change to each GameObject in the selection. |
| Hint | Low | Use Hint to provide additional guidance to readers who are working on their own. It might be a reminder of a technique, or a clue on how to complete an exercise. | Hint: Enable Dim in the Script Graph window to find your unconnected nodes. |
note
Don't group a series of random tips into a Tips and Tricks section. Instead, add the tips in context, where they are most helpful to the user. If you’re not sure where or how to fit a piece of information in, discuss it in the #unity-style-guide Slack channel.
Style
Keep information boxes a brief as possible. If relevant, include a suggestion or solution. In most cases, an information box contains no more than three sentences.
Always offer warnings and cautions before the information or task they relate to. If you’re not sure where or how to fit it in, discuss it in the #unity-style-guide Slack channel.
Formatting
Where possible, use the information box formatting available in your content platform.
If your platform doesn't have information boxes, then add the callout to the page manually. Use a separate paragraph in the main body of the page. Write the leader (for example, "Note," "Tip," or "Warning") in bold, followed by a colon in regular font. Write the message in the same paragraph as the leader, in regular text with appropriate formatting for the content.
| Example callout for a platform without information boxes |
|---|
Warning: The following task overwrites several files in your Project folder. These cannot be restored after Unity overwrites them. Create a backup before you start this process. |