diff --git a/docs/components/modeler/element-templates/template-metadata.md b/docs/components/modeler/element-templates/template-metadata.md
index f1c58ce32c7..ffdd6f04742 100644
--- a/docs/components/modeler/element-templates/template-metadata.md
+++ b/docs/components/modeler/element-templates/template-metadata.md
@@ -202,7 +202,7 @@ A property can be assigned to a group by setting the [`group` key](./template-pr
 
 ```json
 {
-   ...,
+  ...,
   "groups": [
     {
       "id": "definition",
@@ -231,7 +231,33 @@ A property can be assigned to a group by setting the [`group` key](./template-pr
 
 ## Deprecating a template: `deprecated`
 
-Indicates whether the element template is deprecated.
+- `deprecated` is an optional key.
+
+Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation).
+
+:::info
+By deprecating an element template, you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI.
+:::
+
+The `deprecated` property can be an object or a boolean. If an object, it has the following attributes:
+
+- `message: String`: A message to display to the user
+- `documentationRef : String`: A link to documentation, i.e., to describe upgrade migration procedures
+
+This information allows users to make sense of the deprecation and understand how to migrate to an undeprecated template:
+
+```json
+{
+  ...,
+  "deprecated": {
+    "message": "Migrate to My Other Custom Task",
+    "documentationRef": "https://localhost/migrate-to-other"
+  },
+  ...
+}
+```
+
+When `deprecated` is a boolean (`true`), a deprecation hint appears in the properties panel without further help for the user:
 
 ```json
 {
@@ -240,3 +266,7 @@ Indicates whether the element template is deprecated.
   ...
 }
 ```
+
+:::tip
+Review the [upstream documentation](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#overview) to learn more about template evolution and the template lifecycle.
+:::
diff --git a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md
index 0184ba2b75c..ffdd6f04742 100644
--- a/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md
+++ b/versioned_docs/version-8.8/components/modeler/element-templates/template-metadata.md
@@ -231,7 +231,33 @@ A property can be assigned to a group by setting the [`group` key](./template-pr
 
 ## Deprecating a template: `deprecated`
 
-Indicates whether the element template is deprecated.
+- `deprecated` is an optional key.
+
+Use `deprecated` to mark a [template as deprecated](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#deprecation).
+
+:::info
+By deprecating an element template, you prevent its _future use_. Users will no longer see the template when choosing a template, changing an element's type, or creating a new element. Existing uses continue to work, with a deprecation hint shown in the modeler UI.
+:::
+
+The `deprecated` property can be an object or a boolean. If an object, it has the following attributes:
+
+- `message: String`: A message to display to the user
+- `documentationRef : String`: A link to documentation, i.e., to describe upgrade migration procedures
+
+This information allows users to make sense of the deprecation and understand how to migrate to an undeprecated template:
+
+```json
+{
+  ...,
+  "deprecated": {
+    "message": "Migrate to My Other Custom Task",
+    "documentationRef": "https://localhost/migrate-to-other"
+  },
+  ...
+}
+```
+
+When `deprecated` is a boolean (`true`), a deprecation hint appears in the properties panel without further help for the user:
 
 ```json
 {
@@ -240,3 +266,7 @@ Indicates whether the element template is deprecated.
   ...
 }
 ```
+
+:::tip
+Review the [upstream documentation](https://github.com/bpmn-io/element-templates/blob/main/docs/LIFE_CYCLE.md#overview) to learn more about template evolution and the template lifecycle.
+:::