diff --git a/docs/framework/upgrade.md b/docs/framework/upgrade.md
index d60f77c358d0175b86b179cea79a0926278debe2..a445b8a8f6fea6399531ef712e5b9b8172186319 100644
--- a/docs/framework/upgrade.md
+++ b/docs/framework/upgrade.md
@@ -38,6 +38,10 @@ Each class in the `CRM_Upgrade_Incremental_php` corresponds to a major release o
 | `php public function upgrade_X_Y_Z() ` | Perform any changes in a specific queue order for version X.Y.Z. During this function you *MUST* call `php $upgrade->processSQL($rev)`. Without calling this function the X.Y.Z.sql.tpl file will not be executed |
 | `php public function setPostUpgradeMessage() ` | Called after each incremental upgrade. Any messages generated by this function will be displayed to site-administrators *after* the upgrade has completed. (This is called several times – once for each incremental upgrade.) |
 
+## Upgrading message templates
+
+Message templates that need upgrading should be declared under `CRM_Upgrade_Incremental_MessageTemplates::getTemplateUpdates()`. The upgrade script will pick them up from there (5.4+)
+
 ## Tips: Prefer simple SQL semantics over API/BAO/DAO
 
 When writing upgrade steps in PHP its preferable to use direct sql queries rather than relying on BAOs and DAOs as they may change between versions. Whereas writing SQL is more rigorous. Further it is preferable to write SQL statements especially if it involves adding or removing columns, indexes from database tables. There are helper functions such as `CRM_Core_BAO_SchemaHandler::dropIndexIfExists()`, `CRM_Upgrade_Form::addColumn()`, `CRM_Upgrade_Form::dropColumn()`. These helper functions don't depend on version specific business logic and also help protect against hard database fails by checking if what your trying to add or drop exists already.