diff --git a/src/docs/configuration/upgrade_schema.diviner b/src/docs/configuration/upgrade_schema.diviner
index be4146b384..4374d8f81a 100644
--- a/src/docs/configuration/upgrade_schema.diviner
+++ b/src/docs/configuration/upgrade_schema.diviner
@@ -1,29 +1,36 @@
 @title Upgrading Schema
 @group config
 
 This document describes how to upgrade the database schema.
 
 = Prerequisites =
 
 This document assumes you've already initialized the MySQL database and
 configured your Phabricator environment. If you haven't, see
 @{article:Configuration Guide}.
 
 = Loading patches =
 
 To upgrade your database schema to the latest version, just run this command:
 
   PHABRICATOR_ENV=<your_config> path/to/phabricator/scripts/sql/upgrade_schema.php
 
-This will install all the patches that are new since you installed, or since the last time you ran this script.
+NOTE: Make sure you put 'PHABRICATOR_ENV=...' at the beginning of the line, not
+in the middle. The shell won't parse environmental variables declared after the
+command. You can also ##export PHABRICATOR_ENV=...## in your ~/.bashrc or
+~/.profile or similar, depending on which shell you use and how your system is
+configured.
+
+This will install all the patches that are new since you installed, or since the
+last time you ran this script.
 
 If your configuration uses an unprivileged user to connect to the database, you
 may have to override the default user so the schema changes can be applied with
 root or some other admin user:
 
   PHABRICATOR_ENV=<your_config> path/to/phabricator/scripts/sql/upgrade_schema.php -u <user> -p <pass>
 
 You can avoid the prompt the script issues by passing the ##-f## flag (for
 example, if you are scripting the upgrade process).
 
   PHABRICATOR_ENV=<your_config> path/to/phabricator/scripts/sql/upgrade_schema.php -f