diff --git a/INSTALL/old/2_3to2_4-UPGRADE.txt b/INSTALL/old/2_3to2_4-UPGRADE.txt
deleted file mode 100644
index 2a6514f76..000000000
--- a/INSTALL/old/2_3to2_4-UPGRADE.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-# 1. Upgrade procedure from v2.3 to v2.4
-# it is assumed that the upgrade happens from an up-to-date 2.3 instance
-# It is a good idea to back up your MISP installation and data before upgrading to a new release.
-
-# 2. git pull the latest version of MISP from https://github.com/MISP/MISP.git
-cd /var/www/MISP
-git pull
-git checkout tags/$(git describe --tags `git rev-list --tags --max-count=1`)
-# if the last shortcut doesn't work, specify the latest version manually
-# example: git checkout tags/v2.4.XY
-# the message regarding a "detached HEAD state" is expected behaviour
-# (you only have to create a new branch, if you want to change stuff and do a pull request for example)
-
-# 3. Update CakePHP to the latest supported version
-cd /var/www/MISP
-rm -rf app/Lib/cakephp/
-git submodule update --init --recursive
-
-# 4. delete everything from MISP's cache directory to get rid of the cached models
-find /var/www/MISP/app/tmp/cache/ -type f -not -name 'empty' -delete
-
-# 5. clear the old submodule cached entry for CakeResque
-cd /var/www/MISP
-git rm --cached app/Plugin/CakeResque/
-
-# 6. make sure that your database is backed up
-mysqldump -u [misp_mysql_user] -p [misp_database] > /home/[my_user]/misp_db_pre_migration.sql
-
-# 7. upgrade your database with the new tables / fields introduced in 2.4
-cd /var/www/MISP/INSTALL
-mysql -u [misp_mysql_user] -p [misp_database] < upgrade_2.4.sql
-
-# 8. run the upgrade script from within the application
-# simply navigate to Administration -> Administrative Tools -> "Upgrade to 2.4"
-# Once that has completed successfully run the 2.3->2.4 cleanup script
-# simply navigate to Administration -> Administrative Tools -> "2.3->2.4 cleanup script"
-
-# If everything went fine, switch the system to live:
-# Administration -> Server Settings -> MISP Settings -> MISP.live -> True
-# NOTE: if nothing happens, please check the permissions of the config files in /var/www/MISP/app/Config/
-# and make sure the webserver has the write permissions on them:
-# chown -R www-data:www-data /var/www/MISP/app/Config/
-
-# Let us know if you run into any issues during or after the upgrade
diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md
new file mode 100644
index 000000000..95c2bcbd6
--- /dev/null
+++ b/docs/UPGRADE.md
@@ -0,0 +1,9 @@
+# Upgrading MISP
+
+!!! note
+ As time goes by this space will be populated with certain upgrade specific tasks that might at the time of this writing still be in the [MISP-book](https://www.circl.lu/doc/misp/)
+
+!!! warning
+ If you are a MISP developer reading this.
+ Always aim to avoid having to write anything about a specific upgrade procuder. We strive to make our upgrades as seamless as possible and no extra steps should be needed, alas, extreme circumstances sometimes need thos extreme measures.
+ We have been warned.
diff --git a/docs/old-2_3to2_4-UPGRADE.md b/docs/old-2_3to2_4-UPGRADE.md
new file mode 100644
index 000000000..5d358f5d4
--- /dev/null
+++ b/docs/old-2_3to2_4-UPGRADE.md
@@ -0,0 +1,63 @@
+# 0. Upgrade procedure from v2.3 to v2.4
+!!! notice
+ It is assumed that the upgrade happens from an up-to-date 2.3 instance
+ It is a good idea to back up your MISP installation and data before upgrading to a new release.
+
+# 1. git pull the latest version of MISP from the [repo](https://github.com/MISP/MISP.git)
+```
+cd /var/www/MISP
+git pull
+git checkout tags/$(git describe --tags `git rev-list --tags --max-count=1`)
+# if the last shortcut doesn't work, specify the latest version manually
+# example: git checkout tags/v2.4.XY
+# the message regarding a "detached HEAD state" is expected behaviour
+# (you only have to create a new branch, if you want to change stuff and do a pull request for example)
+```
+
+# 2. Update CakePHP to the latest supported version
+```
+cd /var/www/MISP
+rm -rf app/Lib/cakephp/
+git submodule update --init --recursive
+```
+
+# 3. delete everything from MISP's cache directory to get rid of the cached models
+```
+find /var/www/MISP/app/tmp/cache/ -type f -not -name 'empty' -delete
+```
+
+# 4. clear the old submodule cached entry for CakeResque
+```
+cd /var/www/MISP
+git rm --cached app/Plugin/CakeResque/
+```
+
+# 5. make sure that your database is backed up
+```
+mysqldump -u [misp_mysql_user] -p [misp_database] > /home/[my_user]/misp_db_pre_migration.sql
+```
+
+# 6. upgrade your database with the new tables / fields introduced in 2.4
+```
+cd /var/www/MISP/INSTALL
+mysql -u [misp_mysql_user] -p [misp_database] < upgrade_2.4.sql
+```
+
+# 7. run the upgrade script from within the application
+!!! notice
+ simply navigate to Administration -> Administrative Tools -> "Upgrade to 2.4"
+ Once that has completed successfully run the 2.3->2.4 cleanup script
+ simply navigate to Administration -> Administrative Tools -> "2.3->2.4 cleanup script"
+
+!!! notice
+ If everything went fine, switch the system to live:
+ Administration -> Server Settings -> MISP Settings -> MISP.live -> True
+
+!!! notice
+ If nothing happens, please check the permissions of the config files in /var/www/MISP/app/Config/
+ and make sure the webserver has the write permissions on them:
+ ```bash
+ chown -R www-data:www-data /var/www/MISP/app/Config/
+ ```
+
+Let us know if you run into any issues during or after the upgrade
diff --git a/mkdocs.yml b/mkdocs.yml
index 8bff072d8..246a0f941 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -76,6 +76,9 @@ nav:
- 'Amazon S3 attachments': 'CONFIG.s3-attachments.md'
- 'S/MIME': 'CONFIG.SMIME.md'
- Update MISP: 'UPDATE.md'
+ - Upgrading MISP: 'UPGRADE.md'
+ - Old guides:
+ - '2.3 to 2.4 upgrade': 'old-2_3to2_4-UPGRADE.md'
- About:
- 'MISP Release Notes': 'Changelog.md'
- 'License': 'license.md'