kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Update styleguide.md to add Notes usage guidelines

Browse source
This commit is contained in:
Mike Lewis 2019-07-01 04:28:18 +00:00 committed by Evan Read
parent bc71d0b461
commit 1af71196c0
1 changed files with 18 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/development/documentation/styleguide.md
View file

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