An .env.example file or a secrets documentation page is often the first thing a new engineer opens, and unclear entries there create disproportionate friction — a missing explanation for one variable can block someone for an entire afternoon. This guide covers the English for documenting environment variables and secrets clearly.

Key Vocabulary

Required vs. optional variable — a distinction that must be stated explicitly for every entry, since an undocumented required variable causes a startup failure, while an undocumented optional one causes silent misconfiguration. “DATABASE_URL is required — the application will not start without it. LOG_LEVEL is optional and defaults to ‘info’ if omitted.”

Secret rotation — the process of periodically replacing a credential (API key, password, token) with a new one, described in documentation so operators know the procedure and cadence. “API keys are rotated every 90 days. The rotation procedure is documented in RUNBOOK.md — do not rotate manually without following that process, since it also requires updating the value in three downstream services.”

Placeholder value — an obviously fake example value used in documentation or .env.example files, chosen to be unmistakably not a real secret. “Use a placeholder like sk_test_xxxxxxxxxxxx in the example file, never a real key, even a revoked one — it’s too easy for someone to copy-paste it by mistake.”

Scope (of a credential) — what a specific secret is allowed to access, described explicitly so engineers understand blast radius if it leaks. “This token is scoped to read-only access on the orders table. It cannot write, and it cannot access any other table, which limits the impact if it’s ever exposed.”

Local vs. shared secret — a distinction between a secret each developer generates individually for local development and one that’s shared across the team (and usually stored in a secrets manager, not a repo). “STRIPE_TEST_KEY is a shared secret — pull it from the team vault. JWT_LOCAL_SIGNING_KEY is local — generate your own with openssl rand -hex 32, it doesn’t need to match anyone else’s.”

Common Phrases

• “This variable is required; the app will not start without it.”
• “Defaults to [value] if not set.”
• “Pull this from [secrets manager/vault], never commit it to the repo.”
• “This credential is scoped to [specific access] — it cannot [specific restriction].”
• “Rotate this every [interval] following [procedure/runbook].”

Example Sentences

Documenting a required variable in .env.example: *”# Required. PostgreSQL connection string. App will fail to start without this.

Format: postgres://user:password@host:port/dbname

DATABASE_URL=”*

Documenting an optional variable with its default behavior: *”# Optional. Controls log verbosity: debug | info | warn | error.

Defaults to ‘info’ if not set.

LOG_LEVEL=”*

Explaining where to get a shared secret, without exposing it in the repo: *”# Required. Get this value from 1Password vault ‘Engineering Secrets’ > ‘Stripe Test Keys’.

Do not request this in Slack — use the vault link in the onboarding doc.

STRIPE_SECRET_KEY=”*

Writing a short onboarding note about secrets handling: “None of the secrets in this project should ever be committed, even to a private branch. If you accidentally commit one, don’t just delete it in a follow-up commit — it’s still in git history. Rotate the credential immediately and let #security know.”

Professional Tips

• Mark every variable required or optional explicitly, and state the default value for optional ones — this alone eliminates most “why won’t the app start” onboarding questions.
• Never put a real secret, even an expired or revoked one, in an example file — use an obviously fake placeholder so copy-paste mistakes are visually catchable.
• State the scope of a credential in its documentation — “read-only, orders table only” tells a reader the actual blast radius if it leaks, which matters for incident response later.
• Document where to retrieve a shared secret, not just that it exists — “pull from the vault” without a specific path just relocates the confusion.
• If a secret is ever committed by mistake, the documented procedure should say explicitly: rotate it, don’t just delete the commit — git history retains it regardless.

Practice Exercise

1. Write a documented .env.example entry for a required variable, including format and consequence if missing.
2. Write an entry for an optional variable, including its default value.
3. Write a short onboarding note explaining what to do if a secret is accidentally committed.