improve .env documentation

.env_example

@@ -1,36 +1,74 @@
 # JWT secret key: For local testing, the value doesn't matter. In production,
-# this needs to be populated with a randomly generated key (see README.md).
-# This will be used to sign the JWT.
+# this needs to be populated with a randomly generated key. This will be used
+# to sign the JWT.
+#
+# Deployment TL;DR: Set this in the app's environment secrets.
+
 JWT_SECRET="something_hard_to_guess"
 
+
+# Log level: Customize the logging level. By default, it's INFO. This can be
+# set to any of the Python logging module's levels.
+#
+# Deployment TL;DR: Don't set this manually anywhere.
+
+# LOG_LEVEL="INFO"
+
+
 # SMTP server to use for sending emails to users. For development, you can
 # create an Ethereal account to test emails (https://ethereal.email/). In
 # production, refer to the README.md file for instructions.
+#
+# Deployment TL;DR: Set these in the app's environment variables.
+
 SMTP_SERVER="smtp-relay.gmail.com"
 SMTP_PORT=587
 
-# SMTP authentication: Not needed if using a trusted SMTP relay
+
+# SMTP authentication: Not needed if using a trusted SMTP relay. For local
+# development, you can set these to the username/password of the test email
+# server (e.g., Ethereal Email).
+#
+# Deployment TL;DR: Don't set these manually anywhere.
+
 # SMTP_PASSWORD="EXAMPLE"
 # SMTP_USER="[email protected]"
 
-# These already have default values in config.py, but you can override them
-# here if needed.
+# Email settings: These already have default values in config.py, but you can
+# override them here if needed.
+#
+# Deployment TL;DR: Don't set these manually anywhere.
+
 # EMAIL_FROM="[email protected]"
 # EMAIL_FROM_NAME="GSA SmartPay"
 # EMAIL_SUBJECT="GSA SmartPay Training"
 
+
 # Datastores: For local testing, these defaults should be fine. In production,
 # these will be automatically populated from the cloud.gov VCAP_SERVICES data.
+#
+# Deployment TL;DR: Don't set these manually anywhere.
+
 REDIS_HOST="localhost"
 REDIS_PORT=6379
 REDIS_PASSWORD=""
 DB_URI="postgres://postgres:postgres@localhost:5432/postgres"
 
-# Base URL: The app needs to know what base URL to append to links. The default
-# is fine for local development. In production, this needs to be set to the
-# live website's URL.
+
+# Base URL: The app needs to know what base URL to append to links. In
+# production, this needs to be set to the live website's URL.
+#
+# Deployment TL;DR: Set this in the app's environment variables.
+
 BASE_URL="https://training.smartpay.gsa.gov"
 
-# These are configured via config.py, but you can override them here if needed.
+
+# OAuth server information. In production, AUTH_CLIENT_ID will be populated by
+# The VCAP_SERVICES data. AUTH_AUTHORITY_URL needs to be set appropriately in
+# each environment.
+#
+# Deployment TL;DR: Don't set AUTH_CLIENT_ID manually anywhere. Set
+# AUTH_AUTHORITY_URL in the app's environment variables.
+
 AUTH_CLIENT_ID="test_client_id"
 AUTH_AUTHORITY_URL="http://localhost:8080/uaa"