Update styleguide.md to add Notes usage guidelines
This commit is contained in:
parent
bc71d0b461
commit
1af71196c0
1 changed files with 18 additions and 1 deletions
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue