diff --git a/docs/en/changelogs/3.1.0.md b/docs/en/changelogs/3.1.0.md
index b7b65082d..e36f91576 100644
--- a/docs/en/changelogs/3.1.0.md
+++ b/docs/en/changelogs/3.1.0.md
@@ -238,6 +238,23 @@ a standard PHP installation, and need to be added manually through `CURLOPT_CAIN
 Although it is not recommended, you can restore the old insecure behaviour with
 the following configuration: `RestfulService::set_default_curl_option(CURLOPT_SSL_VERIFYPEER, false)`.
 
+### Deprecation API {#deprecation}
+
+The `[api:Deprecation]` API generates deprecation notices to help you future-proof your code.  
+Calls to ceprecated methods will only produce errors if the API was deprecated in the 
+release equal to or earlier than the "notification version" (currently set to "3.1.0").
+	
+If you change the notification version to 3.1.0-dev, then only methods deprecated in older versions
+(e.g. 3.0) will trigger notices, and the other methods will silently pass.  This can be useful if
+you don't yet have time to remove all calls to deprecated methods.
+
+	Deprecation::notification_version('3.1.0-dev');
+
+On the other hand, if you want to identify which APIs will be removed in the next minor release (3.2.0),
+you can enable those warnings and future-proof your code already.
+
+	Deprecation::notification_version('3.2.0');
+
 ### Other
 
  * `TableListField`, `ComplexTableField`, `TableField`, `HasOneComplexTableField`, `HasManyComplexTableField` and `ManyManyComplexTableField` have been removed from the core and placed into a module called "legacytablefields" located at https://github.com/silverstripe-labs/legacytablefields