Secret Placeholder Conventions for Documentation and Examples

Learn how to choose clearly artificial placeholder values for secrets in documentation and examples. This guide helps technical writers and developers avoid accidentally exposing real credentials.

Read this when

Writing docs that include tokens, API keys, or credential snippets
Updating examples that may be scanned by secret-detection tooling

Secret placeholder conventions

Choose placeholders that are easy to understand yet clearly artificial.

Recommended style

Favor descriptive examples such as example-openai-key-not-real or example-discord-bot-token.
When writing shell commands, use ${OPENAI_API_KEY} instead of short token-like strings.
Ensure examples are obviously fabricated and relevant to their context (provider, channel, authentication method).

Avoid these patterns in docs

The literal PEM private key header or footer text.
Prefixes that mimic active credentials, for instance sk-..., xoxb-..., or AKIA....
Bearer tokens that look authentic, copied from execution logs.

Example

# Good
export OPENAI_API_KEY="example-openai-key-not-real"

# Better (when the doc is about env wiring)
export OPENAI_API_KEY="${OPENAI_API_KEY}"