Placeholder or Variable Text

On this page

Placeholder Text Guidelines
Placeholder Explanation Guidelines

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 is 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.

Placeholder Text Guidelines

When creating placeholder text, use the following guidelines.

Note

To learn about showing placeholders for API resources, see API Placeholders.

Guidelines

Example

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. Use a consistent convention throughout the documentation set per the programming language.

.. code-block:: console
   mongod --port <portNumber> \
          --dbpath <tempDatabasePath> \
          --setParameter ttlMonitorEnabled=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
Capitalize the first letter of each word after the first word (called camelCase)
Never capitalize the first word

Note

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.

Don't sacrifice clarity for brevity.
Create descriptive and meaningful placeholders.

device; not dev

installationDirectory; not installDir

mode; not ######## (a series representing a number of digits)

Placeholder Explanation Guidelines

When explaining a placeholder, use the following guidelines:

Guideline

Example

Use a sentence to describe the placeholder parameter.

mongod --port <portNumber> \
       --dbpath <tempDatabasePath> \
       --setParameter ttlMonitorEnabled=false

port is the unique number for the mongod service. The default value is 27017.

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.

mongod --port <portNumber> \
       --dbpath <tempDatabasePath> \
       --setParameter ttlMonitorEnabled=false

Parameter	Type	Necessity	Description
dbpath	string	Required	Root-relative file path for the temporary database.
port	integer	Required	Unique number for this `mongod` service. The default value is `27017`.
setParameter	array	Required	List of key-value pairs that pass instructions to the `mongod` service.

Avoid standalone clauses that begin with where.

mongod --port <portNumber> \
       --dbpath <tempDatabasePath> \
       --setParameter ttlMonitorEnabled=false

where port is the unique number for the mongod service. The default value is 27017.

Back

Placeholders for APIs

Plurals