diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md
index 92562fc20..cdef87793 100644
--- a/docs/en/03_Upgrading/index.md
+++ b/docs/en/03_Upgrading/index.md
@@ -1126,7 +1126,22 @@ All your assets should be loading properly now.
 This is a good point to commit your changes to your source control system before moving on to the next step.
 
 
-## Step 10 - Running your upgraded site for the first time {#step10}
+## Step 10 - Update database class references {#step10}
+
+If you've updated your class names to use namespaces you will need to reflect those changes in any existing database fields. For example, if you've renamed your `HomePage` class to `App\HomePage` then the database `ClassName` column needs to be updated to point to the `App\HomePage` class, otherwise the CMS will tell you that the page is obsolete. This also applies to polymorphic relationships.
+
+There is no automated way to do this, but you can use the list generated in .upgrade.yml and copy it to `app/_config/legacy.yml`, removing any classes that don't extend DataObject.
+
+```
+SilverStripe\ORM\DatabaseAdmin:
+  classname_value_remapping:
+    HomePage: App\HomePage
+```
+
+This will automatically update affected columns when you first build the database.
+
+
+## Step 11 - Running your upgraded site for the first time {#step11}
 
 You're almost across the finish line.