diff --git a/docs/index.md b/docs/index.md
index 88d3be6ef43dd4f69c6c4eb725ce183092140ed4..6fa1cf1a92c5aee242b5c337397cd08cdbb12a16 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,30 +1,20 @@
 SimpleSAMLphp Documentation
 ===========================
 
- * [Installing SimpleSAMLphp](simplesamlphp-install)
-    * [Upgrade notes for version 1.18](simplesamlphp-upgrade-notes-1.18)
-    * [Upgrade notes for version 1.17](simplesamlphp-upgrade-notes-1.17)
-    * [Upgrade notes for version 1.16](simplesamlphp-upgrade-notes-1.16)
-    * [Upgrade notes for version 1.15](simplesamlphp-upgrade-notes-1.15)
-    * [Upgrade notes for version 1.14](simplesamlphp-upgrade-notes-1.14)
-    * [Upgrade notes for version 1.13](simplesamlphp-upgrade-notes-1.13)
-    * [Upgrade notes for version 1.12](simplesamlphp-upgrade-notes-1.12)
-    * [Upgrade notes for version 1.11](simplesamlphp-upgrade-notes-1.11)
-    * [Upgrade notes for version 1.10](simplesamlphp-upgrade-notes-1.10)
-    * [Upgrade notes for version 1.9](simplesamlphp-upgrade-notes-1.9)
-    * [Upgrade notes for version 1.8](simplesamlphp-upgrade-notes-1.8)
-    * [Upgrade notes for version 1.7](simplesamlphp-upgrade-notes-1.7)
-    * [Upgrade notes for version 1.6](simplesamlphp-upgrade-notes-1.6)
-    * [Upgrade notes for version 1.5](simplesamlphp-upgrade-notes-1.5)
-    * [Installation from the repository](simplesamlphp-install-repo)
-    * [Changelog](simplesamlphp-changelog)
- * [Using SimpleSAMLphp as a SAML Service Provider](simplesamlphp-sp)
+ * Installation and upgrading
+  * [Installing SimpleSAMLphp](simplesamlphp-install)
+  * [Upgrade notes](simplesamlphp-upgrade-notes)
+  * [Installation from the repository](simplesamlphp-install-repo)
+  * [Changelog](simplesamlphp-changelog)
+ * Using SimpleSAMLphp as a SAML Service Provider
+  * [Service Provider Quickstart](simplesamlphp-sp)
   * [Hosted SP Configuration Reference](./saml:sp)
   * [IdP remote reference](simplesamlphp-reference-idp-remote)
   * [Configuring HTTP-Artifact](./simplesamlphp-artifact-sp)
   * [Using scoping](./simplesamlphp-scoping)
   * [Holder-of-Key profile](simplesamlphp-hok-sp)
- * [Identity Provider QuickStart](simplesamlphp-idp)
+ * Using SimpleSAMLphp as a SAML Identity Provider
+  * [Identity Provider QuickStart](simplesamlphp-idp)
   * [IdP hosted reference](simplesamlphp-reference-idp-hosted)
   * [SP remote reference](simplesamlphp-reference-sp-remote)
   * [Use case: Setting up an IdP for G Suite (Google Apps)](simplesamlphp-googleapps)
diff --git a/docs/simplesamlphp-install.md b/docs/simplesamlphp-install.md
index 7f04c2074d620f03cd250a2e2f879414adbf2d2d..11805b95d18da193ca00a7468f01ca9c1de34671 100644
--- a/docs/simplesamlphp-install.md
+++ b/docs/simplesamlphp-install.md
@@ -60,6 +60,10 @@ Go to the directory where you want to install SimpleSAMLphp and extract the arch
 
 ## Upgrading from a previous version of SimpleSAMLphp
 
+Before starting the upgrade, review the relevant
+[upgrade notes](simplesamlphp-upgrade-notes) for any relevant
+changes.
+
 Extract the new version:
 
 ```
diff --git a/docs/simplesamlphp-upgrade-notes.md b/docs/simplesamlphp-upgrade-notes.md
new file mode 100644
index 0000000000000000000000000000000000000000..1d24616eb0b232eebd95572efb835cb7b6ffc548
--- /dev/null
+++ b/docs/simplesamlphp-upgrade-notes.md
@@ -0,0 +1,24 @@
+SimpeSAMLphp Upgrade Notes
+==========================
+
+See the following pages for important information for users upgrading
+from older versions of SimpleSAMLphp:
+
+    * [Upgrade notes for version 1.18](simplesamlphp-upgrade-notes-1.18)
+    * [Upgrade notes for version 1.17](simplesamlphp-upgrade-notes-1.17)
+    * [Upgrade notes for version 1.16](simplesamlphp-upgrade-notes-1.16)
+    * [Upgrade notes for version 1.15](simplesamlphp-upgrade-notes-1.15)
+    * [Upgrade notes for version 1.14](simplesamlphp-upgrade-notes-1.14)
+    * [Upgrade notes for version 1.13](simplesamlphp-upgrade-notes-1.13)
+    * [Upgrade notes for version 1.12](simplesamlphp-upgrade-notes-1.12)
+    * [Upgrade notes for version 1.11](simplesamlphp-upgrade-notes-1.11)
+    * [Upgrade notes for version 1.10](simplesamlphp-upgrade-notes-1.10)
+    * [Upgrade notes for version 1.9](simplesamlphp-upgrade-notes-1.9)
+    * [Upgrade notes for version 1.8](simplesamlphp-upgrade-notes-1.8)
+    * [Upgrade notes for version 1.7](simplesamlphp-upgrade-notes-1.7)
+    * [Upgrade notes for version 1.6](simplesamlphp-upgrade-notes-1.6)
+
+A detailed list of changes in each release can be found in the
+[Changelog](simplesamlphp-changelog).
+
+