diff --git a/docs/source/upgrading-notes.md b/docs/source/upgrading-notes.md
deleted file mode 100644
index 9ffeabb1..00000000
--- a/docs/source/upgrading-notes.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Upgrading JupyterHub and its databases
-
-## Definitions
-db type: sqlite, postgres, mysql, others???
-db fields: individual fields in a database table
-
-## Basic use cases
-- [ ] Simple upgrade - no database fields changed; no db type change
-- [ ] Field changes  - database fields added, deleted or changed by a new JHub release/functionality; no db type change
-
-## More complex use cases
-- [ ] Field changes - database fields added, deleted or changed by user; no db type change
-- [ ] db type change (i.e. sqlite to postgres) - fields may or may not change; db type does change
-
-## Process
-- Remind admins to back up Hub databases
-- Possibly remind admins to make sure single user notebook data is saved/backed up
-- Admin notify users (if desired) of planned upgrade
-
-**Multi-step upgrade vs all at once**??
-- Migrate database type (Hub at same release level) user-initiated
-- Add/change/delete fields (Hub at same release level) user-initiated
-- Add/change/delete files (Hub initiated - in prep for JHub release upgrade)
-- Upgrade Hub to 0.7 after
-
-- Upgrade/changes to: CHP, authenticators, spawners
-
-## Other topics
-- limitations of sqlite upgrade
-- upgrade hub first or upgrade db first???
-
-## Tools
-
-### Using alembic for database migrations
-
-[Alembic][] ([docs for alembic][]) provides change management scripts for a
-relational database, using [SQLAlchemy][] as the underlying engine. This
-section will explain how alembic is used to upgrade JupyterHub's database.
-
-Looking at the JupyterHub source code from the root of the repo, we see:
-
-- `jupyterhub/alembic.ini` This file contains configuration information for
-  the database. It is used when the `alembic` command is run to access the
-  location of the change management scripts.
-- `jupyterhub/alembic` This directory contains the migration
-  environment used by alembic. The `env.py` file in this directory is a
-  Python file that is run when alembic does a database migration and may be
-  customized if necessary.
-  
-
-
-
-
-[Alembic]: https://bitbucket.org/zzzeek/alembic
-[docs for alembic]: http://alembic.zzzcomputing.com/en/latest/
-[SQLAlchemy]: http://www.sqlalchemy.org
-
-- scripts
-- db tools
diff --git a/docs/source/upgrading.md b/docs/source/upgrading.md
index 23cfde12..4b765c4d 100644
--- a/docs/source/upgrading.md
+++ b/docs/source/upgrading.md
@@ -38,9 +38,12 @@ Next, shutdown the JupyterHub service.
 Follow directions that correspond to your package manager, `pip` or `conda`,
 for the new JupyterHub release. These directions will guide you to the
 specific command. In general, `pip install -U jupyterhub` or
-`conda upgrade jupyter`
+`conda upgrade jupyterhub`
 
 ### Run `jupyterhub upgrade-db`
 
+To run the upgrade process for JupyterHub databases, enter:
 
-## Upgrading a sqlite database
+```
+jupyterhub upgrade-db
+```