diff --git a/doc/filters/escape.rst b/doc/filters/escape.rst
index 574724e35b..7b6b4f44c1 100644
--- a/doc/filters/escape.rst
+++ b/doc/filters/escape.rst
@@ -39,7 +39,7 @@ And here is how to escape variables included in JavaScript code:
 The ``escape`` filter supports the following escaping strategies for HTML
 documents:
 
-* ``html``: escapes a string for the **HTML body** context.
+* ``html``: escapes a string for the **HTML body** context, or for HTML attributes values **inside quotes**.
 
 * ``js``: escapes a string for the **JavaScript** context.
 
@@ -50,7 +50,7 @@ documents:
 * ``url``: escapes a string for the **URI or parameter** contexts. This should
   not be used to escape an entire URI; only a subcomponent being inserted.
 
-* ``html_attr``: escapes a string for the **HTML attribute** context.
+* ``html_attr``: escapes a string for the **HTML attribute** context, **without quotes** around HTML attribute values.
 
 Note that doing contextual escaping in HTML documents is hard and choosing the
 right escaping strategy depends on a lot of factors. Please, read related
@@ -90,6 +90,25 @@ to learn more about this topic.
             {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
         {% endautoescape %}
 
+.. tip::
+
+    The ``html_attr`` escaping strategy can be useful when you need to 
+    escape a **dynamic HTML attribute name**.
+
+    .. code-block:: html+twig
+
+        <p {{ your_html_attr|e('html_attr') }}="attribute value">
+    
+    It can also be used for escaping **dynamic HTML attribute value** if 
+    it is not quoted, but this is **less performant**. Instead, it is recommended 
+    to quote the HTML attribute value and use the ``html`` escaping strategy.
+
+    .. code-block:: html+twig
+
+        <p data-content="{{ content|e('html') }}">
+        {# is equivalent to, but is less performant #}
+        <p data-content={{ content|e('html_attr') }}>
+
 Custom Escapers
 ---------------