diff --git a/docs/en/changelogs/3.0.0.md b/docs/en/changelogs/3.0.0.md
index d5fe36ee3..2f82f218a 100644
--- a/docs/en/changelogs/3.0.0.md
+++ b/docs/en/changelogs/3.0.0.md
@@ -14,17 +14,18 @@
 
 ## Upgrading ##
 
-### References to sapphire replaced with ModulePath ###
+### sapphire renamed to framework ###
 
-`sapphire` module has been renamed to `framework` for new installations of SilverStripe.
+`sapphire` has been renamed to `framework`.
 
-Existing code bases can retain `sapphire` as the framework directory name, and a new template variable
-`$ModulePath` is now used in place of hardcoding "sapphire" in the core code base, this allows easier
-transitions if you want to rename the framework directory.
+Please ensure the framework now resides in the new folder when upgrading.
 
-In your templates, `$ModulePath(framework)` gives whatever directory the SilverStripe framework resides in.
-It takes the value from the `FRAMEWORK_DIR` constant, which is automatically worked out based on where the
-framework directory is, but can be set manually by defining `FRAMEWORK_DIR` in your `_ss_environment.php` file.
+Here's a list of steps to check:
+
+ * Remove your existing `sapphire` directory, and replace with `framework` from the new SilverStripe 3.0 package
+ * Rename references of `sapphire` to `framework` in `.htaccess`, `web.config` and `/usr/bin/sake` (the last is only necessary if you use `sake`)
+ * Find and replace any references to `sapphire` in your custom code to `framework`. In your PHP code, you can use the constant `FRAMEWORK_DIR`,
+which points to the framework directory, and in the templates you can use `$ModulePath(framework)`
 
 ### New ORM: More flexible and expressive querying via `DataList` ###