diff options
| -rw-r--r-- | doc/development/documentation/styleguide.md | 19 |
1 files changed, 18 insertions, 1 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 02b157b4515..0d82f905bf3 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -577,7 +577,7 @@ nicely on different mobile devices. ## Alert boxes -Whenever you want to call the attention to a particular sentence, +Whenever you need to call special attention to particular sentences, use the following markup for highlighting. _Note that the alert boxes only work for one paragraph only. Multiple paragraphs, @@ -585,6 +585,23 @@ lists, headers, etc will not render correctly. For multiple lines, use blockquot ### Note +Notes catch the eye of most readers, and therefore should be used very sparingly. +In most cases, content considered for a note should be included: + +- As just another sentence in the previous paragraph or the most-relevant paragraph. +- As its own standalone paragraph. +- As content under a new subheading that introduces the topic, making it more visible/findable. + +#### When to use + +Use a note when there is a reason that most or all readers who browse the +section should see the content. That is, if missed, it’s likely to cause +major trouble for a minority of users or significant trouble for a majority +of users. + +Weigh the costs of distracting users to whom the content is not relevant against +the cost of users missing the content if it were not expressed as a note. + ```md NOTE: **Note:** This is something to note. |