(DOCSP-11392): Updated Call-outs page (#63)

* (DOCSP-11392): Updated Call-outs page

* copy review

* Update source/style-guide/style/callouts.txt

Co-authored-by: Anthony Sansone <[email protected]>

* Apply suggestions from code review

Co-authored-by: Anthony Sansone <[email protected]>

Co-authored-by: Anthony Sansone <[email protected]>

Author: melissamahoney-mongodb

source/style-guide/style/callouts.txt

@@ -0,0 +1,103 @@
+.. _callouts:
+
+========================
+Callouts and Admonitions
+========================
+
+.. default-domain:: mongodb
+
+.. include:: /includes/styles/corrections.rst
+
+Callouts or admonitions emphasize important or
+helpful information. Use callouts sparingly to avoid clutter on
+the page and to preserve visual impact. 
+
+Callout Types
+-------------
+
+You can use the following callouts:
+
+.. list-table::
+   :widths: 20 60 30
+   :header-rows: 1
+
+   * - Callout Type
+     - Description
+     - Directive
+   * - Tip
+     - Provides useful information that might improve product
+       performance or make procedures easier to follow. Tips provide
+       the following benefits:
+
+       - Help users learn techniques or procedures
+       - Show alternative ways of doing something
+       - Provide shortcuts
+       - Provide helpful (but not essential) information
+
+     - ``.. tip:: <title>``
+
+   * - Note
+     - Provides information that emphasizes or supplements information
+       in the text. A note can provide information that applies only in
+       certain cases.
+     - ``.. note:: <title>``
+   * - Important
+     - Presents an important or essential point. As a rule, users must
+       pay attention to important callouts to complete a task or
+       understand a topic.
+     - ``.. important:: <title>``
+   * - Warning
+     - Alerts users to potential hazards or highlights critical
+       information. Use a warning for situations in which users could
+       lose data, compromise data integrity, or disrupt operations if
+       they don't follow instructions carefully.
+     - ``.. warning:: <title>``
+   * - Example
+     - Presents a scenario that illustrates or demonstrates a concept in
+       the text.
+     - ``.. example:: <title>``
+   * - See
+     - Provides a link to a topic or section directly related to the
+       preceding text. You might use ``see`` to link to content with
+       necessary procedures, definitions, or deployment considerations
+       and impacts.
+     - ``.. see::``
+   * - See also
+     - Provides a link to topics or sections that are generally related 
+       to or provide useful context for the preceding text. You might
+       use ``seealso`` to link to content that provides background
+       information, deeper context, or common related tasks.
+     - ``.. seealso::``
+
+Callout Guidelines
+------------------
+When creating callouts, use the following guidelines:
+
+-  Use the callout type to convey the kind of information you want 
+   to communicate. Don't rely on color to convey intensity.
+
+-  Use the correct {+rst+} directive to create the callout. Don't 
+   attempt to create callouts using boldface, headings, or custom
+   :abbr:`CSS (Cascading Style Sheets)`.
+
+-  Avoid nesting callouts inside tables and other elements.
+
+-  Avoid nesting code blocks inside callouts.
+
+-  Place a callout as close as possible to the information that it
+   emphasizes or clarifies.
+
+-  Don't "stack" callouts of the same type (for example, by following
+   one labeled note directly with another labeled note). Instead, use
+   separate paragraphs or an unordered list within a single callout.
+   You can have callouts of different types follow one
+   another.
+
+The following callouts might appear in existing documentation but are
+deprecated. Don't use these callouts in new content:
+
+- ``.. admonition::``
+- ``.. caution::``
+- ``.. danger::``
+- ``.. topic::``
+

source/style-guide/style/index.txt

@@ -12,6 +12,7 @@ instructions for applying style conventions.
    :maxdepth: 1
 
    /style-guide/style/abbreviations
+   /style-guide/style/callouts
    /style-guide/style/capitalization
    /style-guide/style/citations
    /style-guide/style/code-examples
@@ -27,7 +28,6 @@ instructions for applying style conventions.
    /style-guide/style/lists
    /style-guide/style/messages
    /style-guide/style/names
-   /style-guide/style/notations
    /style-guide/style/numbers
    /style-guide/style/parameters
    Placeholders for APIs </style-guide/style/cloud-account-info>

source/style-guide/style/notations.txt

@@ -94,8 +94,8 @@ Use the following guidelines for text in table cells:
    for matrix-type tables that use an X or other marker to indicate
    support. In such cases, blank cells are acceptable (see the third
    example at the end of this topic).
--  When showing a notation (for example, a note or warning) in a table,
-   use the guidelines in :ref:`notations`.
+-  When showing a call-out (for example, a note or warning) in a table,
+   use the guidelines in :ref:`callouts`.
 -  If space in a table is constrained, you can use abbreviations and
    symbols that you wouldn't normally use in body text (such as % for
    percent).
@@ -104,10 +104,10 @@ Use the following guidelines for text in table cells:
 Table Footnotes
 ---------------
 
-If a notation (for example, a note or warning) applies to the entire
-table, place the content in a regular notation preceding the table. If
-a notation applies only to the content in a certain cell, place the
-notation in that cell. However, if a notation applies to all of the
+If a callout (for example, a note or warning) applies to the entire
+table, place the content in a regular callout preceding the table. If
+a callout applies only to the content in a certain cell, place the
+callout in that cell. However, if a call-out applies to all of the
 content in a row or column, or to the content in two or more cells, you
 can use footnotes.