diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md
index 2ba2e9280..ef00a87fc 100644
--- a/docs/getting-started/upgrading.md
+++ b/docs/getting-started/upgrading.md
@@ -15,67 +15,44 @@ Your operating system may occasionally provide security updates. We recommend se
 
 Docker releases updates periodically to their engine. We recommend reading their release notes and upgrading accordingly. Please see the [Docker documentation](https://docs.docker.com/) for more details.
 
-Finally, we provide a helpful binary called `dokku-update`. This is a recommended package that:
-
-- Can be installed separately, so upgrading Dokku will not affect the running of this package.
-- Automates many of the upgrade instructions for you.
-- Provides a clean way for us to further enhance the upgrade process in the future.
-
-When installing from source, this is available from `contrib/dokku-update`, and is also available on Debian and RPM-based systems from our package repositories under the name `dokku-update`.
 
 ## Migration Guides
 
 Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.
 
-### 0.5 Migration Guide
+- [Upgrading to 0.21](/docs/appendices/0.21.0-migration-guide.md)
+- [Upgrading to 0.20](/docs/appendices/0.20.0-migration-guide.md)
+- [Upgrading to 0.10](/docs/appendices/0.10.0-migration-guide.md)
+- [Upgrading to 0.9](/docs/appendices/0.9.0-migration-guide.md)
+- [Upgrading to 0.8](/docs/appendices/0.8.0-migration-guide.md)
+- [Upgrading to 0.7](/docs/appendices/0.7.0-migration-guide.md)
+- [Upgrading to 0.6](/docs/appendices/0.6.0-migration-guide.md)
+- [Upgrading to 0.5](/docs/appendices/0.5.0-migration-guide.md)
 
-- [0.5 Migration Guide](/docs/appendices/0.5.0-migration-guide.md)
 
-### 0.6 Migration Guide
+## Before upgrading
 
-- [0.6 Migration Guide](/docs/appendices/0.6.0-migration-guide.md)
-
-### 0.7 Migration Guide
-
-- [0.7 Migration Guide](/docs/appendices/0.7.0-migration-guide.md)
-
-### 0.8 Migration Guide
-
-- [0.8 Migration Guide](/docs/appendices/0.8.0-migration-guide.md)
-
-### 0.9 Migration Guide
-
-- [0.9 Migration Guide](/docs/appendices/0.9.0-migration-guide.md)
-
-### 0.10 Migration Guide
-
-- [0.10 Migration Guide](/docs/appendices/0.10.0-migration-guide.md)
-
-### 0.20 Migration Guide
-
-- [0.20 Migration Guide](/docs/appendices/0.20.0-migration-guide.md)
-
-## Upgrade Instructions
-
-If Dokku was installed via `apt-get install dokku` or `bootstrap.sh` (most common), upgrade with:
+If you'll be updating docker simultaneously, it's recommended that you stop all
+applications before upgrading:
 
 ```shell
-# update your local apt cache
-sudo apt-get update
-
-# stop each running app
-# for 0.11.4 and newer versions, use
+# for 0.11.4 and newer versions, use:
 dokku ps:stopall
+
 # for versions between 0.8.1 and 0.11.3, use
 dokku --quiet apps:list | xargs -L1 dokku ps:stop
+
 # for versions versions older than 0.8.1, use
 dokku --quiet apps | xargs -L1 dokku ps:stop
+```
 
-# update dokku and its dependencies
-sudo apt-get install -qq -y dokku herokuish sshcommand plugn gliderlabs-sigil
+## After upgrading
 
-# rebuild all of your applications
-dokku ps:rebuildall # rebuilds all applications
+After upgrading, you should rebuild the applications to take advantage of any
+new buildpacks that were released:
+
+```shell
+dokku ps:rebuildall
 ```
 
 > If you have any applications deployed via the `tags` or `tar` commands, do not run the `ps:rebuildall` command,
@@ -88,12 +65,38 @@ dokku ps:rebuildall # rebuilds all applications
 > Please see the [images documentation](/docs/deployment/methods/images.md) and [tar documentation](/docs/deployment/methods/tar.md)
 > for instructions on rebuilding applications deployed by those plugins.
 
-### Upgrade From Source
+
+## Upgrading using `dokku-update`
+
+We provide a helpful binary called `dokku-update`. This is a recommended package that:
+
+- Can be installed separately, so upgrading Dokku will not affect the running of this package.
+- Automates many of the upgrade instructions for you.
+- Provides a clean way for us to further enhance the upgrade process in the future.
+
+When installing from source, this is available from `contrib/dokku-update`, and is also available on Debian and RPM-based systems from our package repositories under the name `dokku-update`.
+
+
+## Upgrading using `apt`
+
+If Dokku was installed in a Debian or Ubuntu system, via `apt install dokku` or `bootstrap.sh`, you can upgrade with `apt`:
+
+```shell
+# update your local apt cache
+sudo apt update
+
+# update dokku and its dependencies
+sudo apt install -qq -y dokku herokuish sshcommand plugn gliderlabs-sigil
+
+# or just upgrade every package:
+sudo apt upgrade
+```
+
+## Upgrading from source
 
 If you installed Dokku from source (less common), upgrade with:
 
 ```shell
-dokku --quiet apps | xargs -L1 dokku ps:stop # stops each running app
 cd ~/dokku
 git pull --tags origin master
 
@@ -102,7 +105,6 @@ sudo DOKKU_BRANCH=master make install
 
 # upgrade to debian package-based installation
 sudo make install
-dokku ps:rebuildall # rebuilds all applications
 ```
 
 To upgrade Herokuish from source, upgrade with: