Merge branch 'selhorn-alert-box-style-guide' into 'master'

Changed alert box guidance

See merge request gitlab-org/gitlab!49249

doc/development/documentation/styleguide/index.md

@@ -970,7 +970,7 @@ search engine optimization (SEO), use the imperative, where possible.
 
 For guidelines on capitalizing headings, see the section on [capitalization](#capitalization).
 
-NOTE: **Note:**
+NOTE:
 If you change an existing title, be careful. In-page [anchor links](#anchor-links),
 links in the GitLab application, and links from external sites can break.
 
@@ -979,7 +979,7 @@ links in the GitLab application, and links from external sites can break.
 Headings generate anchor links when rendered. `## This is an example` generates
 the anchor `#this-is-an-example`.
 
-NOTE: **Note:**
+NOTE:
 [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in
 GitLab 13.4, [product badges](#product-tier-badges) used in headings aren't
 included in the generated anchor links. For example, when you link to
@@ -1510,100 +1510,72 @@ example:
 
 ## Alert boxes
 
-When you need to call special attention to particular sentences, use the
-following markup to create highlighted alert boxes.
+Use alert boxes to call attention to information.
 
-Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers
-don't render correctly. For multiple lines, use [blockquotes](#blockquotes)
-instead.
+Alert boxes are generated when the words `NOTE:` or `WARNING:` are followed by a
+line break. For example:
 
-Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>).
-In the GitLab product help, alert boxes appear as plain Markdown text.
+```markdown
+NOTE:
+This is something to note.
+```
 
-These alert boxes are used in the GitLab documentation. These aren't strict
-guidelines, but for consistency you should try to use these values:
+To display an alert box for multiple paragraphs, lists, or headers, use
+[blockquotes](#blockquotes) instead.
 
-| Color  | Markup     | Default keyword | Alternative keywords                                                 |
-|--------|------------|-----------------|----------------------------------------------------------------------|
-| Blue   | `NOTE:`    | `**Note:**`     |                                                                      |
-| Yellow | `CAUTION:` | `**Caution:**`  | `**Warning:**`, `**Important:**`                                     |
-| Red    | `DANGER:`  | `**Danger:**`   | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` |
-| Green  | `TIP:`     | `**Tip:**`      |                                                                      |
+Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>).
+In the GitLab product help, alert boxes appear as plain text.
 
 ### Note
 
-Notes indicate additional information that's of special use to the reader.
-Notes are most effective when used _sparingly_. Try to avoid them. Too many notes
-can make topics difficult to scan, and create an overly busy page.
+Use notes sparingly. Too many notes can make topics difficult to scan.
 
-Instead of adding a note, try one of these alternatives:
+Instead of adding a note:
 
-- Re-write the sentence as part of the most-relevant paragraph.
-- Put the information into its own standalone paragraph.
-- Put the content under a new subheading that introduces the topic, which makes
-  it more visible.
+- Re-write the sentence as part of a paragraph.
+- Put the information into its own paragraph.
+- Put the content under a new subheading.
 
-If you must use a note, use the following formatting:
+If you must use a note, use this format:
 
 ```markdown
-NOTE: **Note:**
+NOTE:
 This is something to note.
 ```
 
-How it renders on the GitLab documentation site:
+It renders on the GitLab documentation site as:
 
-NOTE: **Note:**
+NOTE:
 This is something to note.
 
-### Tip
-
-```markdown
-TIP: **Tip:**
-This is a tip.
-```
-
-How it renders on the GitLab documentation site:
-
-TIP: **Tip:**
-This is a tip.
-
-### Caution
-
-```markdown
-CAUTION: **Caution:**
-This is something to be cautious about.
-```
-
-How it renders on the GitLab documentation site:
-
-CAUTION: **Caution:**
-This is something to be cautious about.
+### Warning
 
-### Danger
+Use a warning to indicate deprecated features, or to provide a warning about
+procedures that have the potential for data loss. 
 
 ```markdown
-DANGER: **Warning:**
-This is a breaking change, a bug, or something very important to note.
+WARNING:
+This is something to be warned about.
 ```
 
-How it renders on the GitLab documentation site:
+It renders on the GitLab documentation site as:
 
-DANGER: **Warning:**
-This is a breaking change, a bug, or something very important to note.
+WARNING:
+This is something to be warned about.
 
 ## Blockquotes
 
-For highlighting a text inside a blue blockquote, use this format:
+For highlighting a text inside a blockquote, use this format:
 
 ```markdown
 > This is a blockquote.
 ```
 
-which renders on the [GitLab documentation site](https://docs.gitlab.com) as:
+It renders on the GitLab documentation site as:
 
 > This is a blockquote.
 
-If the text spans across multiple lines it's OK to split the line.
+If the text spans multiple lines, you can split them.
 
 For multiple paragraphs, use the symbol `>` before every line:
 
@@ -1616,7 +1588,7 @@ For multiple paragraphs, use the symbol `>` before every line:
 > - Second item in the list
 ```
 
-Which renders to:
+It renders on the GitLab documentation site as:
 
 > This is the first paragraph.
 >
@@ -1752,11 +1724,10 @@ If a feature is deprecated, include a link to a replacement (when available):
 ```
 
 You can also describe the replacement in surrounding text, if available. If the
-deprecation isn't obvious in existing text, you may want to include a warning,
-such as:
+deprecation isn't obvious in existing text, you may want to include a warning:
 
 ```markdown
-DANGER: **Deprecated:**
+WARNING:
 This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by
 [Feature name](link-to-feature-documentation).
 ```
@@ -1780,15 +1751,14 @@ voters to agree.
 
 #### End-of-life for features or products
 
-When a feature or product enters the end-of-life process, indicate its
-status prominently. Use the `Danger` [alert](#alert-boxes) with the `**Important**`
-keyword directly below the page header, or the sub-header for the feature or product.
-Link to the deprecation and removal issues, if possible.
+When a feature or product enters its end-of-life, indicate its status by
+creating a [warning alert](#alert-boxes) directly following its relevant header.
+If possible, link to its deprecation and removal issues.
 
 For example:
 
 ```markdown
-DANGER: **Important:**
+WARNING:
 This feature is in its end-of-life process. It is [deprecated](link-to-issue)
 for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X.
 ```