Examples and placeholders

Best practices on how to provide examples and placeholder text so that users can relate to them

---

Use meaningful examples

• Make sure example and placeholder text is always meaningful and matches real use cases
• Avoid exposing real addresses or proprietary information through examples

👍 Correct

user@domain.com

👎 Don't use

bobama@whitehouse.com

handle@domain.tld

Format standard text as italics

Format example text and text the user is expected to replace or enter as italics.

How to deal with sample code

Note

For more information on how to deal with code using Markdown, see the Markdown Styleguide (opens new window).

Block-level code text

When example text that the user is expected to replace occurs in code text, do the following:

• make it all caps
• separate words with underscores
• Introduce the code sample you're about to show and explain what it allows to do
• Describe the placeholder values in a unordered list, sorting them in the order they appear in the code block

👍 Correct

1. Customize your account settings by adding this code to example.py.

import asyncio
import aiohttp
import json

URL: myurl.com
ACCOUNT: ACCOUNT_ID

Where:

• ACCOUNT_ID is the ID of your account

👎 Don't use

1. Customize this code by replacing ACCOUNT_ID with the ID of your account and add it to example.py.

import asyncio
import aiohttp
import json

URL: myurl.com
ACCOUNT: ACCOUNT_ID

Where:

• ACCOUNT_ID is the ID of your account

Inline-level code text

• format it as italics
• make it all caps
• separate words with underscores

👍 Correct

ACCOUNT_ID is the ID of your account

👎 Don't use

Replace $ACCOUNT_ID with the ID of your account

Replace ACCOUNT-ID with the ID of your account

Replace {ACCOUNTID} with the ID of your account