(DOCSP-11408) Update placeholder page

Author: Anthony Sansone

source/style-guide/style/placeholder-variable-text.txt

@@ -1,147 +1,176 @@
 .. _placeholder-variable-text:
 
-===========================
-Placeholder (Variable) Text
-===========================
+============================
+Placeholder or Variable Text
+============================
 
-.. include:: /style-guide/includes/page-needs-update.rst
+.. default-domain:: mongodb
 
-Placeholder text (also referred to as variable text or replaceable
-text) stands for an object whose specific name is unknown to us.
-Placeholders are included when documenting syntax for how a command or
-path should be constructed. Users supply the relevant value for the
-placeholder when using the command or syntax.
+.. include:: /includes/styles/corrections.rst
+
+Use placeholder text for a value when you:
+
+- don't know its specific value
+- don't or shouldn't use an example value
+
+Use placeholders when demonstrating how a command or path should be
+constructed. Users supply the relevant value for the placeholder when
+using the command or syntax. When using placeholders, instruct users to
+replace the placeholders with the relevant values.
+
+Placeholder text can also referred to as *variable text* or
+*replaceable text*.
 
 Placeholder text usually indicates the type of element that's being
 represented. For example, *directoryName* would likely indicate the
 name of a directory.
 
-.. note::
 
-   Placeholder text is distinct from *environment variables*.
-   Environment variables have established formats and names, such as
-   ``$account``, and their values are set in the system by users and
-   used consistently. By contrast, a placeholder is given a relevant
-   value by the user at the time that the user runs the code or types
-   the path. For information about formatting environment variables,
-   see :ref:`text-formatting`.
+Placeholder Text Guidelines
+---------------------------
 
 When creating placeholder text, use the following guidelines.
 
 .. note::
 
-   For specific information about showing placeholders for account
-   information such as account numbers, usernames, passwords, and API
-   keys, see :ref:`cloud-account-info`.
+   To learn about showing placeholders for API resources, see
+   :ref:`cloud-account-info`.
 
 .. list-table::
-   :widths: 50 50
+   :widths: 60 40
    :header-rows: 1
 
    * - Guidelines
 
      - Example
 
-   * - Within regular text, show placeholder text in italics.
+   * - Within regular or inline text, show placeholder text in italics
+       using the {+rst+} ``:samp::`` role and curly braces. Any text
+       within curly braces inside the ``:samp:`` role renders in
+       italics.
 
-       Within code samples, use the RST ``:samp:`` directive, and
-       enclose the placeholder text in curly braces. This formatting
-       renders the placeholder in italics.
+     - :samp:`mongod --port {portNumber} --dbpath {tempDatabasePath}`
 
-       If you can't apply text formatting to the code, enclose
+   * - Use the ``.. code-block:: <lexer>`` for multiline code examples.
+
+       As you can't apply text formatting to the code, enclose
        placeholders in punctuation that doesn't have any other special
-       use in the code. For example, use angle brackets or curly
-       braces. Use a consistent convention throughout the documentation
-       set.
+       use in the code. Use a consistent convention throughout the documentation set per the programming language.
+
+     - .. code-block:: rst
+          :copyable: false
+
+          .. code-block:: console
+
+             mongod --port <portNumber> \
+                    --dbpath <tempDatabasePath> \
+                    --setParameter ttlMonitorEnabled=false
 
-     - :samp:`nova boot {serverName} --image {image} --flavor {flavor}
-       --nic net-id=net1_id`
+       .. code-block:: console
+          :copyable: false
+
+          mongod --port <portNumber> \
+                 --dbpath <tempDatabasePath> \
+                 --setParameter ttlMonitorEnabled=false
 
    * - Use lowercase letters except when showing a multiple-word
        placeholder.
 
-       To show a multiple-word placeholder, don't separate the words
-       with spaces or symbols. To distinguish the words in the
-       placeholder, capitalize the first letter of each word after the
-       first word (called camelCase). Don't capitalize the first word.
+       To show a multiple-word placeholder:
+
+       - Don't separate the words with spaces or symbols
+       - Capitalize the first letter of each word after the first word
+         (called :wikipedia:`camelCase </Camel_case>`)
+       - Never capitalize the first word
 
        .. note::
-          Use lowercase and camelCase unless you have to follow the
-          conventions of the programming language. For example, you
-          might need to use underscores (account_ID) or all capitals
-          (ACCOUNT_ID).
+          Use lowercase and camelCase unless you need to follow the
+          conventions of the programming language.
+
+     - *password*, *eventTypeName*, *apiKey*, *hostId*
+
+   * - Use one or more whole words to represent a placeholder.
 
-     - *password* *serverName* *apiKey* *tenantId*
+       - Don't sacrifice clarity for brevity.
+       - Create descriptive and meaningful placeholders.
 
-   * - In general, use one or more whole words to represent a
-       placeholder. Don't sacrifice clarity for brevity. Create
-       placeholders that are descriptive and meaningful.
+     - *device*; not *dev*
 
-     - *device* (instead of *dev*)
+       *installationDirectory*; not *installDir*
 
-       *installationDirectory* (instead of *installDir*)
+       *mode*; not *########* (a series representing a number of
+       digits)
 
-       *mode* (instead of *########*)
+Placeholder Explanation Guidelines
+----------------------------------
 
-When explaining a placeholder, use the following guidelines.
+When explaining a placeholder, use the following guidelines:
 
 .. list-table::
    :widths: 40 60
    :header-rows: 1
 
-   * - Guidelines
+   * - Guideline
 
      - Example
 
-   * - Avoid stand-alone clauses that begin with *where*. Instead, use
-       a sentence.
-
-     - *Use:*
-
-       **https://dfw.bigdata.api.MongoDBcloud.com/v1.0/yourAccountId/**
-
-       *yourAccountId* is your actual account number, which is returned
-       as part of the authentication service response.
+   * - Use a sentence to describe the placeholder parameter.
 
-       *Avoid:*
+     - .. code-block:: console
 
-       **https://dfw.bigdata.api.MongoDBcloud.com/v1.0/yourAccountId/**
+          mongod --port <portNumber> \
+                 --dbpath <tempDatabasePath> \
+                 --setParameter ttlMonitorEnabled=false
 
-       where *yourAccountId* is your actual account number, which is
-       returned as part of the authentication service response.
+       *port* is the unique number for the ``mongod`` service. The
+       default value is ``27017``.
 
-   * - If you need to explain two or more placeholders, use an
-       unordered list.
+   * - Use a table if you need to explain two or more placeholders.
+       This table should provide the parameter, data type, necessity
+       (*required*, *optional*, or *conditional*), and a description
+       of that parameter.
 
-     - From a supported web browser, type the following URL:
+     - .. code-block:: console
 
-       **http://hostName:portNumber/ed/index.html**
+          mongod --port <portNumber> \
+                 --dbpath <tempDatabasePath> \
+                 --setParameter ttlMonitorEnabled=false
 
-       The placeholders in the URL are defined as follows:
+       .. list-table::
+          :widths: 15 10 10 65
+          :header-rows: 1
+          :stub-columns: 1
 
-       - *hostName* is the name of the host computer on which the
-         application server is installed.
+          * - Parameter
+            - Type
+            - Necessity
+            - Description
 
-       - *portNumber* is the port number assigned to the application
-         server. The default is 8082.
+          * - dbpath
+            - string
+            - Required
+            - Root-relative file path for the temporary database.
 
-   * - Show the placeholder in regular text with the same formatting
-       that it's shown in the path or code. For example, if you can
-       show it in italics, use italics when explaining it. If you
-       first show the placeholder in a code block and need to enclose
-       it in angle brackets, show it in angle brackets and monospace
-       when explaining it.
+          * - port
+            - integer
+            - Required
+            - Unique number for this ``mongod`` service. The default
+              value is ``27017``.
 
-     - *Use:*
+          * - setParameter
+            - array
+            - Required
+            - List of key-value pairs that pass instructions to the
+              ``mongod`` service.
 
-       **https://dfw.bigdata.api.MongoDBcloud.com/v1.0/yourAccountId/**
+   * - Avoid standalone clauses that begin with *where*.
 
-       *yourAccountId* is your actual account number, which is returned
-       as part of the authentication service response.
+     - .. code-block:: console
 
-       *Use:*
+          mongod --port <portNumber> \
+                 --dbpath <tempDatabasePath> \
+                 --setParameter ttlMonitorEnabled=false
 
-       Run the following command, replacing ``<dockerHostName>`` with
-       the name of your Docker host:
+       where *port* is the unique number for the ``mongod`` service.
+       The default value is ``27017``.
 
-       ``docker-machine env <dockerHostName> --shell cmd``