(DOCSP-7337): Updates to Writing Guide ahead of LGTM process.

Author: Anthony Sansone

source/includes/styles/corrections.rst

@@ -0,0 +1,21 @@
+.. raw:: html
+
+   <style type="text/css">
+     table.docutils {
+       width: 100%
+     }
+     code.descname, code.docutils.literal > .pre, code.xref.mongodb.mongodb-alert.docutils.literal {
+       font-size: 90%
+     }
+     div.ui-setting dl.setting dt code.descname {
+       font-size: 100%;
+       font-family: Akzidenz,"Helvetica Neue",Helvetica,Arial,sans-serif;
+       font-weight: 700;
+     }
+     dl.setting > dt > code.descname {
+       font-size: 100%;
+     }
+     caption > .caption-text {
+       text-align: left
+     }
+   </style>

source/style-guide/terminology/terms-for-global-audience.txt

@@ -4,6 +4,8 @@
 Write for a Global Audience
 ===========================
 
+.. include:: /includes/styles/corrections.rst
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -12,22 +14,25 @@ Write for a Global Audience
 
 .. include:: /style-guide/includes/page-needs-update.rst
 
-MongoDB is a global company, with customers in many countries. A small
-amount of content has been translated, but most has not, which means
-that many customers who don't speak English as their first language
-consume our English content. All of the guidelines in this topic
-("Basic writing guidelines") are designed to make content easy to
-understand for all audiences, but the following guidelines will
-especially clarify content for global audiences.
+Developers worldwide use MongoDB. A small amount of content has been
+translated, but most has not, which means that many customers who don't
+speak English as their first language consume our English content. All
+of the guidelines in this topic ("Basic writing guidelines") are
+designed to make content easy to understand for all audiences, but the
+following guidelines will especially clarify content for global
+audiences.
+
+.. _idioms:
+.. _colloquialisms:
 
 Don't Use Idioms or Colloquialisms
 ----------------------------------
 
-An *idiom* is an expression whose meaning can't be derived from the
+An **idiom** is an expression whose meaning can't be derived from the
 literal meaning of the individual words. Some examples are *in a
 nutshell*, *the bottom line*, *across the board*, and *on the fly*.
 
-A *colloquialism* is an expression considered more appropriate to
+A **colloquialism** is an expression considered more appropriate to
 familiar and casual conversation than to formal speech or to formal
 writing. Although we might like to establish a more conversational tone
 in some content, colloquialisms can be hard for non-native English
@@ -42,7 +47,6 @@ alternatives that you can use.
    :widths: 50 50
    :header-rows: 1
 
-
    * - Idiom or colloquialism
      - Alternative
 
@@ -91,14 +95,16 @@ alternatives that you can use.
    * - when you're done
      - when you're finished
 
+.. _metaphors:
+
 Avoid Metaphorical Terms
 ------------------------
 
-A *metaphor* is a figure of speech in which a word or phrase that
-denotes one kind of object or action is used in place of another to
-suggest a likeness or analogy between them. Although some common
-metaphors are easy even for people who don't speak English as a first
-language, avoid them as often as possible.
+A **metaphor** is a figure of speech in which a word or phrase that
+denotes one kind of object or action replaces another to suggest a
+likeness or analogy between them. Although some common metaphors are
+easy even for people who don't speak English as a first language, avoid
+them as often as possible.
 
 The following table provides some examples of metaphorical terms that
 can easily be replaced with one or more words.
@@ -107,7 +113,6 @@ can easily be replaced with one or more words.
    :widths: 50 50
    :header-rows: 1
 
-
    * - Metaphor
      - Alternative
 
@@ -126,6 +131,8 @@ can easily be replaced with one or more words.
    * - the drawback of frequent updates
      - the disadvantage of frequent updates
 
+.. _humor:
+
 Don't Use Humor
 ---------------
 
@@ -136,115 +143,141 @@ literally or figuratively, so don't use it.
 Use Jargon with Care
 --------------------
 
-*Jargon* is the specialized language of a profession. Jargon can be
+**Jargon** is the specialized language of a profession. Jargon can be
 useful for technical audiences, but it can be meaningless to novice
-users and difficult to translate. Don't use jargon if you can
-easily and correctly use a more common or familiar term, or if the
-jargon obfuscates rather than clarifies the meaning. However, if the
-jargon is essential to the technical meaning of the content, use it. If
-the audience isn't highly technical, consider explaining any jargon
-that you use.
+users and difficult to translate.
+
+- Don't use jargon if you can easily and correctly use a more common or
+  familiar term.
+- Don't use jargon if the jargon obfuscates rather than clarifies the
+  meaning.
+- Use jargon if the jargon is essential to the technical meaning of the
+  content.
+- Consider explaining any jargon that you use if the audience isn't
+  highly technical.
 
 The following table lists some jargon typically used in the high tech
 industry and some possible alternatives.
 
 .. list-table::
-   :widths: 25 25 50
+   :widths: 20 5 25 50
    :header-rows: 1
 
    * - Jargon
+     - Part
      - Alternative
      - Examples
 
-   * - abort (verb)
+   * - abort
+     - (v)
      - stop, end, cancel
      - If an error occurs during data entry, the update process stops.
 
-   * - boot, reboot (v)
+   * - boot, reboot
+     - (v)
      - start, restart
      - To apply your changes, restart the server.
 
-   * - bounce (v)
+   * - bounce
+     - (v)
      - restart
      - Restart the service.
 
-   * - box (noun)
+   * - box
+     - (n)
      - computer, server
      - The configuration specifies four servers.
 
-   * - cache (v)
+   * - cache
+     - (v)
      - place in cache
      - For quick access, you can place the command in cache.
 
-   * - debug (v)
+   * - debug
+     - (v)
      - resolve
      - After you resolve the problem, restart the server.
 
-   * - dropped (adj)
+   * - dropped
+     - (adj)
      - discontinued
      - In this release, support for Windows is discontinued.
 
-   * - execute (v)
+   * - execute
+     - (v)
      - run
      - Run the script.
 
-   * - fire, fire up (v)
+   * - fire, fire up
+     - (v)
      - start
      - After repairs are completed, you can start the server.
 
-   * - freeze (v)
+   * - freeze
+     - (v)
      - stop responding
      - If the console stops responding, restart the application.
 
-   * - grayed, grayed out (adj)
+   * - grayed, grayed out
+     - (adj)
      - unavailable, dimmed
      - You can't reduce the size of a Windows server, so options for
        smaller size servers are unavailable.
 
-   * - hang (v)
+   * - hang
+     - (v)
      - stop responding
      - A severe error might cause the server to stop responding.
 
-   * - interface (v)
+   * - interface
+     - (v)
      - connect, communicate, interact
      - Host 1 interacts with Host 2.
 
-   * - kill (v)
+   * - kill
+     - (v)
      - stop, end, terminate
      - You can terminate the process by pressing Ctrl+C.
 
-   * - launch (v)
+   * - launch
+     - (v)
      - start
      - Start the application monitor in debug mode.
 
-   * - machine (n)
-     - computer, server
+   * - machine
+     - (n)
+     - computer, server, host
      - If a UFO lands in the data center, the servers stop working.
 
        .. note::
           When referring to a virtual machine (VM), *machine* is
           correct.
 
-   * - ping (v)
+   * - ping
+     - (v)
      - contact, alert
      - To verify the connection, use the ping command to contact the
        other server.
 
-   * - sanity check (v)
+   * - sanity check
+     - (v)
      - test, evaluate
      - You can use a pre-existing function to evaluate the data that
        users enter.
 
-   * - slave (n, adj)
-     - subordinate, secondary (adj)
+   * - slave
+     - (n, adj)
+     - subordinate, secondary
      - Database replication that uses a master database server and a
        secondary (or slave) database server provides key advantages.
 
-   * - spin up (v)
+   * - spin up
+     - (v)
      - create
      - If you need more capacity, create a new server.
 
-   * - throw (v)
+   * - throw
+     - (v)
      - generate
      - If the program fails, an error is generated.
 
@@ -256,17 +289,17 @@ problems for a global audience and for translation. Sounds, colors,
 animals, gestures, events, and symbols don't convey the same meaning in
 every culture.
 
--  Don't use the names of places, public figures, or holidays. If you
-   must, use examples that represent a variety of cultures or that are
-   internationally recognized. For example, use international cities,
-   such as Paris, New York, Tokyo, London, and Hong Kong.
+- Don't use the names of places, public figures, or holidays. If you
+  must, use examples that represent a variety of cultures or that are
+  internationally recognized. For example, use international cities,
+  such as Paris, New York, Tokyo, London, and Hong Kong.
 
--  Don't use political, religious, ethnic, or historical references.
+- Don't use political, religious, ethnic, or historical references.
 
--  Don't use metaphors that are specific to one culture (for example,
-   an American football metaphor).
+- Don't use metaphors that are specific to one culture (for example,
+  an American football metaphor).
 
-Use generic examples that work in any target market.
+- Use generic examples that work in any target market.
 
 If you create "named" users for extended examples or scenarios, use
 names that represent a variety of ethnic backgrounds, genders, and
@@ -278,23 +311,23 @@ Use Culture-Neutral Graphics
 Use graphics whenever possible to present processes and complex ideas.
 However, be aware of the following possible issues:
 
--  Some users don't typically read from left to right. If a graphics
-   illustrates a sequence, make that sequence explicit by using
-   numbers, arrows, or directional terms.
-
--  Don't rely on color alone to convey meaning. The color red, for
-   example, has different meanings in different countries so could be
-   interpreted differently by different users. Also, colors can have
-   political or religious significance. Use neutral colors as often as
-   possible.
-
--  Don't use a picture of a hand by itself (for example, a hand that is
-   pointing). Almost every hand gesture is offensive to someone. A
-   picture of a hand that is holding an item or interacting with
-   something is generally acceptable.
-
--  Use generic or international images. Some examples are soccer
-   players and equipment, generic landscapes, pens and pencils, and
-   generic images of computer equipment. Avoid using images of men,
-   women, flags, maps, animals, alcohol, trendy objects, historical
-   references, or film, cartoon, or video characters.
+- Some users don't typically read from left to right. If a graphic
+  illustrates a sequence, make that sequence explicit by using numbers,
+  arrows, or directional terms.
+
+- Don't rely on color alone to convey meaning. The color red, for
+  example, has different meanings in different countries so could be
+  interpreted differently by different users. Also, colors can have
+  political or religious significance. Use neutral colors as often as
+  possible.
+
+- Don't use a picture of a hand by itself (for example, a hand that is
+  pointing). Almost every hand gesture is offensive to someone. A
+  picture of a hand that is holding an item or interacting with
+  something is generally acceptable.
+
+- Use generic or international images. Some examples are soccer
+  players and equipment, generic landscapes, pens and pencils, and
+  generic images of computer equipment. Avoid using images of men,
+  women, flags, maps, animals, alcohol, trendy objects, historical
+  references, or film, cartoon, or video characters.