Examples and scenarios Edit

Note: Highlight: Write unbiased examples without revealing personally identifiable information.

Providing examples in documentation helps the reader visualize concepts. Be thoughtful while writing and coming up with fictitious examples and scenarios; sometimes they may be unintentionally biased. As well as writing diverse and inclusive documentation, don’t reveal personally identifiable information such as real names, addresses, phone numbers, email addresses, or financial information. In addition to fictitious examples and scenarios, you can also use placeholder variables such as EMAIL_ADDRESS or PHONE_NUMBER.

In general, write examples and scenarios with a global perspective. Some scenarios may be improbable in some regions, and some may be different altogether. Social customs, politics, events, holidays, sports, traditions, religion, and legal and business practices vary worldwide. Avoid discussing technologies and standards that aren’t adopted worldwide; don’t assume US standards are familiar to everyone. Be thoughtful on how these fictional scenarios would be perceived by a global audience.

For more information, see Writing inclusive documentation and Writing documentation for an international audience.

Example domain names Example domain names

While writing a generic domain name in an example, use example.com, example.org, or example.net.

Top ↑

Example email addresses Example email addresses

For example email addresses, use one of the domains listed in Example domain names.

Example

Tip: Recommended: name@example.com

Top ↑

Example person names Example person names

When you need people’s names and their activities in an example, use fictional character names from non-copyrighted material. Don’t use character names from copyrighted content such as movies, television shows, or books. Also, don’t use real people’s names.

If you can’t think of a fictional character name that is not copyrighted, you can invent new names; although be thoughtful while thinking of new names. Ensure a diverse, inclusive, and global demographic while writing examples with people’s names.

If another guideline specifically defines fictional person names, use those names in your examples.

Top ↑

Example organization names Example organization names

When you need an organization name in an example, use Example Organization. If you need multiple organization names or need to differentiate between two fictional companies, add a description to the organization names. For example, you can use Example Tech Organization and Example Education Organization.

Top ↑

Example phone numbers Example phone numbers

Don’t use real phone numbers in examples.

For phone number examples according to the North American Numbering Plan, use a US number in the range (800) 555-0100 through (800) 555-0199. That range is reserved for use in examples and in fiction.

For international phone number examples, use a US number from the same range and include the country and area codes. For more information about phone number formatting, see Phone numbers.

Examples

Tip: Recommended: (800) 555-0139


Tip: Recommended: +1 800 555 0139

Top ↑

Example IP addresses Example IP addresses

For IPv4 examples, use one of the RFC 5737 addresses reserved for documentation purposes. These addresses are not used on the internet. The use the following three reserved IPv4 addresses:

  • 192.0.2.1
  • 198.51.100.1
  • 203.0.113.1

For IPv4 address ranges, use the following examples:

  • 192.0.2.0/24
  • 198.51.100.0/24
  • 203.0.113.0/24

When you need an IPv6 address example, use values from the RFC 3849 range as follows:

  • 2001:db8::
  • 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
  • 2001:db8:1:1:1:1:1:1
  • 2001:db8:2:2:2:2:2:2
  • 2001:db8:3:3:3:3:3:3
  • 2001:db8:4:4:4:4:4:4

For IPv6 address ranges, use the following example:

  • 2001:db8::/32

Top ↑

Example street addresses Example street addresses

Use different locales and regions, and avoid using real street addresses in examples. Instead, use the following fictional street address:

1000 99th Street
San Francisco, CA 94110
United States of America

Last updated: