diff --git a/templating/debug.rst b/templating/debug.rst
index 28742e83845..8492941771f 100644
--- a/templating/debug.rst
+++ b/templating/debug.rst
@@ -33,14 +33,25 @@ for example, inside your controller::
     The output of the ``dump()`` function is then rendered in the web developer
     toolbar.
 
-The same mechanism can be used in Twig templates thanks to ``dump()`` function:
+In a Twig template, you can use the ``dump`` utility as a function or a tag:
+
+* ``{% dump foo.bar %}`` is the way to go when the original template output
+  shall not be modified: variables are not dumped inline, but in the web
+  debug toolbar;
+* on the contrary, ``{{ dump(foo.bar) }}`` dumps inline and thus may or not
+  be suited to your use case (e.g. you shouldn't use it in an HTML
+  attribute or a ``<script>`` tag).
 
 .. code-block:: html+twig
 
     {# app/Resources/views/article/recent_list.html.twig #}
-    {{ dump(articles) }}
+    {# the contents of this variable are sent to the Web Debug Toolbar #}
+    {% dump articles %}
 
     {% for article in articles %}
+        {# the contents of this variable are display on the web page #}
+        {{ dump(article) }}
+
         <a href="/article/{{ article.slug }}">
             {{ article.title }}
         </a>