What are standard techniques that indicate to the documentation reader that they are to substitute their own appropriate text (e.g. username, domain)?

Question

When reading manuals or guides, I can easily get confused between what is meant to be example text, and what is actually meant to be used.

For example, sometimes the username to login to use a product might be "user". How do I indicate to the new user that "user" is the default account, or that "user" is just an example name?

Are there any standard symbols that could be placed around the text?

Answer 1

In my experience, this combination of points does the job nicely:

• At the beginning of your guide, provide an instruction on how you'll be referencing commands, user-specified text/options, etc. Italic is common for this. For example: text indicates text that you need to provide and should represent actual data, such as your email address, username, password, etc.
• Use consistent formatting options, capitalization, and syntax across your docs.
• Use a common special character to surround user input, such as the already suggested %, <> braces, or [] braces (although I've seen these as marking optional input). Make it explicitly clear if the special characters should be included in the input or not.
• Use a consistent way to reference common user inputs (placeholders) such as "my-user-name", "my-password", "[email protected]", or "". Make sure these are defined with examples at the beginning of your guide.

Here's also what the Microsoft Manual of Style says on the subject of formatting for user input:

User input Usually lowercase, unless case sensitive. Bold or italic, depending on element. If the user input string contains placeholder text, use italic for that text.

An accessibility consideration:

Simple formatting or color won't do for visually impaired users. This calls for the use of good placeholder text to indicate the purpose of the user input, along with some special characters. It also calls for good introductory text before the code block or user interface reference. For example: "On the command line, type the following and replace "my-user-name" with your actual user name."

Answer 2

I prefer angular brackets <> and hyphenated text inside. For example:

URL format: http://<your-host-name>:<your-port-number>.com/

The text should be something that would make it obvious for user to understand that it needs to be replaced with actual value. This also takes case of any accessibility considerations.

Answer 3

As the other anwers show, different practices have been established for various systems.

It is important to differentiate between texts that mainly address people who are aware of such technicalities and texts that address people who are not aware of them.

People who fit into the first group will usually expect this type of substitution because they are used to it. The methods given in the other answers will suffice: these standards have been established for a reason.

Users who are not accustomed to technical writing and the corresponding style of documentation may struggle with such instructions. In addition to optically emphasise the term to be replaced, it may help these users to add remarks for clarification, such as:

In the following code snippet, replace partition with the name of the device you want to create the ext4 filesystem on:

# mkfs.ext4 /dev/partition

Answer 4

Depending on different operating systems/platform, the user is restricted to use special characters.

For example, Windows restricts to use special characters while creating a folder/file but Linux allows to use special characters to use naming a folder/file.

Documentation/manual for a software/platform is prepared by keeping all that in mind.

While researching to answer this I came across this beautiful software documentation document, it mentions

Documentation formats for user-entered commands or codes shall clearly distinguish between literals (to be input exactly as shown) and variables (to be selected by the user).

Answer 5

Robert Lauriston is correct. <> is the proper way to document user input in code in Microsoft Documentation.

Many folks are suggesting using % signs to document user input in documentation, That would be incorrect in Microsoft Documentation.

% signs are used as system environment variables in Microsoft. i.e. %SystemRoot% refers to the installation directory of Windows. (usually: C:\Windows)

Microsoft explains "Environment Variables"

Answer 6

I like the way GitHub documentation handles this by using a different color and style:

Just using a different color is not enough, as there are vision-impaired readers.

Answer 7

I had issues with getting the correct output for various combinations of monospace, italic, and bold in the ever-changing assortment of outputs I was generating from the single-source system I was using at the time, so I use basic ASCII punctuation:

< > : to be provided by the user, for example, MON <application name>

{ } : choose one from a set of items separated by |, for example, LIST { ROLES | USERS }

[ ] : optional, for example, MON [application name>] (MON can be used by itself or followed by the name of an application)

This convention is explained in an "About this documentation" section. If the command is at all complicated, I follow the command syntax with an example.

You'd probably want to use a different set of punctuation if documenting something like XML, where the code is full of angle brackets.

The Microsoft Manual of Style has a good set of conventions if text formatting works for you (see "Command syntax").

Answer 8

%per cent signs% immediately come to my mind, as in "Welcome, %username%!"