Documenting Environment Variables in README

Documenting Environment Variables

Proper environment variable documentation prevents hours of debugging and Slack messages. Every application that uses environment variables should document them clearly in the README.

The .env.example Pattern

Always include a .env.example file in your repository (committed to git) and reference it in your README:

## Configuration

Copy the example environment file:
\`\`\`bash
cp .env.example .env
\`\`\`
Then edit `.env` with your values.

Variable Documentation Table

Use a table for clear, scannable documentation:

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
REDIS_URL	No	redis://localhost:6379	Redis connection for caching
PORT	No	3000	Server port
LOG_LEVEL	No	info	Logging verbosity (debug, info, warn, error)
JWT_SECRET	Yes	-	Secret key for JWT signing (min 32 chars)
SMTP_HOST	No	-	SMTP server for email (if email enabled)

Group by Category

For applications with many variables, group them:

# ── Database ──────────────────────────────
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DATABASE_POOL_SIZE=10

# ── Authentication ────────────────────────
JWT_SECRET=your-secret-key-at-least-32-characters
SESSION_TIMEOUT=3600

# ── External Services ─────────────────────
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=SG...

# ── Application ───────────────────────────
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

Secret Handling Guidance

Add a note about secrets:

> **Important**: Never commit `.env` files with real credentials to git.
> Use a secrets manager (AWS Secrets Manager, Vault, Doppler) for production.
> The `.env` file is listed in `.gitignore`.

Per-Environment Differences

If variables change across environments, document it:

Variable	Development	Staging	Production
NODE_ENV	development	staging	production
DATABASE_URL	Local PostgreSQL	RDS staging	RDS production
LOG_LEVEL	debug	info	warn