diff --git a/components/config/definition.rst b/components/config/definition.rst
index c6353644b88..a8507439544 100644
--- a/components/config/definition.rst
+++ b/components/config/definition.rst
@@ -357,6 +357,10 @@ In order to maintain the array keys use the ``useAttributeAsKey()`` method::
         ->end()
     ;
 
+.. note::
+
+    If using YAML, then the ``'name'`` argument of ``useAttributeAsKey`` has a special meaning and refers to the key of the map (``sf_connection`` and ``default`` in this example). If a child node was defined for the ``connections`` node with the name ``name``, then the key of the map would be lost.
+
 The argument of this method (``name`` in the example above) defines the name of
 the attribute added to each XML node to differentiate them. Now you can use the
 same YAML configuration shown before or the following XML configuration: