diff --git a/docs/simplesamlphp-upgrade-notes-2.0.md b/docs/simplesamlphp-upgrade-notes-2.0.md
index eb1c824542eb097fb77896552de45d838fdb6061..dd52b62dc616697c79c87ab54e0623c9ed7f5d34 100644
--- a/docs/simplesamlphp-upgrade-notes-2.0.md
+++ b/docs/simplesamlphp-upgrade-notes-2.0.md
@@ -1,23 +1,50 @@
 Upgrade notes for SimpleSAMLphp 2.0
 ====================================
 
+SimpleSAMLphp 2.0 is a major new release which has cleaned up support for a
+lot of things that have been marked deprecated in previous SimpleSAMLphp
+releases. The following changes are relevant for installers and/or developers.
+
+Software requirements
+---------------------
 - The minimum PHP version required is now PHP 7.4.
-- Dropped support for Symfony 4
-- Dropped support for Twig 2
+- Dropped support for Symfony 4 and Twig 2.
+
+Not all modules included by default
+-----------------------------------
+The set of modules included in the base installation has been reduced.
+If you used some of the modules that were shipped with SimpleSAMLphp, you now have to manually install them using Composer.
+For example, to use the LDAP module:
+
+  composer require simplesamlphp/simplesamlphp-module-ldap --update-no-dev
+
+Functional changes
+------------------
+- Modules must be enabled through the `module.enable` option in `config.php`. Modules can no longer be enabled by having
+  a file named `enable` or `default-enable` in the module's root directory.
+- SAML AuthnRequests that are signed will have their signature validated unless specifically disabled
+  by setting `validate.authnrequest` to `false`. If unset (or set to true) signatures will be
+  validated if present and requests not passing validation will be refused.
+- In the  core:TargetedID authproc-filter, the `attributename` setting has been renamed to `identifyingAttribute`.
+- The default encryption algorithm is set from `AES128_CBC` to `AES128_GCM`.
+  It is possible to switch back via the `sharedkey_algorithm`. Note however that CBC is vulnerable to the Padding oracle attack.
+- All support for the Shibboleth 1.3 / SAML 1.1 protocol has been removed.
+- Configuration options have been removed:
+  - languages[priorities]
+  - attributes.extradictionaries. Add an attributes.po to your configured theme instead.
+
+Changes relevant for (module) developers
+----------------------------------------
+The following changes are relevant for those having custom developed modules, authentication
+processing filters or interface with the SimpleSAMLphp development API.
+
 - Old JSON-formatted dictionaries have been replaced by gettext / .po-files;
     You can find a migration guide here: https://github.com/simplesamlphp/simplesamlphp/wiki/Migrating-translations-(pre-migration)
 - Old PHP templates have been replaced by Twig-templates; you can find a migration
     guide here: https://github.com/simplesamlphp/simplesamlphp/wiki/Twig:-Migrating-templates
 - The source was completely typehinted; if you have custom authsources or authproc filters, 
     make sure you change them to reflect the method signatures of the base classes.
-- If you used some of the modules that were shipped with SimpleSAMLphp, you now have to manually install them using Composer;
-    For example, to use the ldap-module: bin/composer.phar require simplesamlphp/simplesamlphp-module-ldap --update-no-dev
-- Modules must be enabled through the `module.enable` option in `config.php`. Modules can no longer be enabled by having
-     a file named `enable` or `default-enable` in the module's root directory.
 - If you're using the core:TargetedID authproc-filter, note that the `attributename` setting has been renamed to `identifyingAttribute`.
-- The default encryption algorithm is set from AES128_CBC to AES128_GCM. If you're upgrading from an existing implementation, you may want
-    to manually switch back the `sharedkey_algorithm`. Note that CBC is vulnerable to the Padding oracle attack.
-- In compliancy with SAML2INT, AuthnRequests that are signed will have their signature validated unless specifically disabled by setting `validate.authnrequest` to `false`.  If unset, or set to true, signatures will be validated and requests not passing validation will be refused.
 - The following classes have been migrated to non-static:
   + \SimpleSAML\Utils\Arrays
   + \SimpleSAML\Utils\Attributes
@@ -54,6 +81,3 @@ Upgrade notes for SimpleSAMLphp 2.0
     - lib/SimpleSAML/Store/Memcache.php has been renamed to lib/SimpleSAML/Store/MemcacheStore.php
     - lib/SimpleSAML/Store/Redis.php has been renamed to lib/SimpleSAML/Store/RedisStore.php
 
-- Configuration options removed:
-  - languages[priorities]
-  - attributes.extradictionaries. Add an attributes.po to your configured theme instead.