(DOCSP-11396): Update Tables page (#64)

* (DOCSP-11396): Update Tables page

* Apply suggestions from code review

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

* copy review

* Apply suggestions from code review

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

* copy review 2

* Fix build error from recent merge

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

Author: melissamahoney-mongodb

source/style-guide/style/punctuation.txt

@@ -6,7 +6,7 @@ Punctuation
 
 .. default-domain:: mongodb
 
-.. include:: /includes/style/corrections.rst
+.. include:: /includes/styles/corrections.rst
 
 Use punctuation correctly and consistently. This section provides
 guidelines for using punctuation in MongoDB documentation. For basic

source/style-guide/style/tables.txt

@@ -4,7 +4,9 @@
 Tables
 ======
 
-.. include:: /style-guide/includes/page-needs-update.rst
+.. default-domain:: mongodb
+
+.. include:: /includes/styles/corrections.rst
 
 Text that's difficult to read in paragraph form often becomes clear
 when put into a table. Tables clarify the relationships among
@@ -42,20 +44,20 @@ sentence with a colon.
 Table Titles
 ------------
 
-Tables should normally have titles (captions). However, some tables are
-closely associated with the surrounding text and don't require titles.
-For example, decision matrixes and tables within tasks, procedures, and
-tutorials don't require numbers or titles.
+Tables in conceptual topics should normally have titles (captions).
+However, some tables are closely associated with the surrounding text
+and don't require titles. For example, decision matrixes and tables
+within tasks, procedures, and tutorials don't require titles.
 
 When creating table titles, use the following guidelines:
 
 - Use sentence-style capitalization for table titles. However, for
   words that are always uppercase or always lowercase, match that case.
 - Don't start a table title with an article (*a*, *an*, *the*).
 - Don't end a table title with a period or colon.
-- Place the title above the table, not below it, and tag it as bold.
-- Don't manually number table titles. If titles should be numbered, the
-  style sheet will number them.
+- Place the title above the table, not below it, and format it in 
+  **boldface**.
+- Don't number table titles.
 - Make table titles concise; limit them to one line if possible.
 - Make table titles descriptive:
 
@@ -71,7 +73,7 @@ Column Headers
 
 Use the following guidelines for text in column headers:
 
--  Use sentence-style capitalization in column headers. However, for
+-  Use headline-style capitalization in column headers. However, for
    words that are always uppercase or always lowercase, match that
    case.
 -  Use singular nouns for column headers, unless the context requires
@@ -94,7 +96,7 @@ 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 call-out (for example, a note or warning) in a table,
+-  When showing a callout (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
@@ -107,7 +109,7 @@ Table Footnotes
 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
+callout in that cell. However, if a callout applies to all of the
 content in a row or column, or to the content in two or more cells, you
 can use footnotes.
 
@@ -123,10 +125,10 @@ can use footnotes.
 -  Place the footnote text at the end of the table, either in a final
    row that spans the entire table or under the last row in the table.
 
--  Use superscript numbers to indicate the footnotes in the cells to
-   which they apply. If numbers might be confusing (for example,
-   because the text in the cells are numerical values), use lowercase
-   letters instead.
+-  Use :rst:`{+rst+} markup </restructuredtext.html#footnotes>`
+   to set the footnotes in the cells to which they apply. If
+   numbers might be confusing (because maybe the text in the
+   cells are numerical values), use symbols instead.
 
    -  A footnote cited in a column header applies to the entire column.
    -  A footnote cited in a table cell applies to the text in that
@@ -141,12 +143,18 @@ following additional guidelines:
 
 -  For tables that describes JSON or XML attributes, write the first
    sentence of a description with an implied subject. For example, if
-   the attribute is name, the description might be as follows: "Server
-   name, which becomes the initial host name of the server"
--  For attributes, include the valid values and default value at the
-   end of the description. Use the formats "Valid values are *n* and
-   *n*." and "The default is *n*." For example, "Valid values are
-   ``true`` and ``false``." and "The default is ``false``."
+   the attribute is name, the description might be as follows:
+   "Initial hostname of the server."
+-  For attributes or parameters, include the valid values and default 
+   value at the end of the description. 
+   
+   - For request parameters, use the formats "Application accepts 
+     *n* or *n*." and "The default is *n*." For example, "Atlas accepts
+     ``true`` or ``false``." and "The default is ``false``."
+   - For response parameters, use the formats "Application returns 
+     *n* or *n*." and "The default is *n*." For example, "Atlas returns
+     ``true`` or ``false``." and "The default is ``false``."
+
 -  If table descriptions or construction is complex, consider using a
    definition list or itemized list instead of a table.
 -  Avoid putting definition lists in tables.
@@ -164,25 +172,25 @@ The following table explains the different parts of the preceding URL:
      - Explanation
 
    * - ``swift://``
-     - The prefix that passes file system requests to the Swift file
+     - Prefix that passes file system requests to the Swift file
        system.
 
    * - ``acontainer``
-     - The name of the container in Swift that contains the objects to
+     - Name of the container in Swift that contains the objects to
        be accessed. Container names must conform to RFC952 restrictions
        for host names—that is, the characters A-Z, numbers 0-9, and the
        hyphen (-).
 
        Nonconforming container names are inaccessible by swiftfs.
 
    * - ``aservice``
-     - A user-friendly "service" name. A service name maps to a
+     - User-friendly "service" name. A service name maps to a
        collection of configuration entries in the Hadoop core-site.xml
        file that specify where the container is located (for example,
        MongoDB-dfw).
 
    * - ``/path/to/files``
-     - The name of the object or objects in Swift to be referenced.
+     - Name of the object or objects in Swift to be referenced.
        Although Swift doesn't support paths, swiftfs attempts to
        interpret names that look like paths and behave appropriately.
        For example, an input path named ``/path/to/*`` would qualify
@@ -254,37 +262,30 @@ The following matrix indicates which upgrade scenarios are supported:
      - X
      -
 
-   * - 3 (OpenCenter) to any version
-     -
-     - X
-
-   * - 2 (Alamo) to any version
-     -
-     - X
-
 The following chart compares these top content management systems (CMSs):
 
 .. list-table::
    :widths: 20 40 40
    :header-rows: 1
+   :stub-columns: 1
 
    * -
      - Drupal
      - WordPress
 
-   * - **Homepage**
+   * - Homepage
      - www.drupal.org
      - www.wordpress.org
 
-   * - **About**
+   * - About
      - Drupal is a powerful, developer-friendly tool for building
        complex sites. Like most powerful tools, it requires some
        expertise and experience to operate.
      - WordPress began as an innovative, easy-to-use blogging platform.
        With an ever-increasing repertoire of themes, plug-ins, and
        widgets, this CMS is also widely used for other website formats.
 
-   * - **Example sites**
+   * - Example sites
      - Community Portal: Fast Company, Team Sugar
      - Social Networking: PlayStation Blog
 
@@ -294,6 +295,6 @@ The following chart compares these top content management systems (CMSs):
 
        News Publishing:The New York Observer
 
-   * - **Installation**
+   * - Installation
      - Drupal Installation Forum
      - WordPress Installation Forum