diff --git a/src/doc/macros.rst b/src/doc/macros.rst
index 560827e6fc4ff8b0238f16ca8d76b2c682bce505..5329ca6ddde49dbef439659d4904b07ed3f2bef9 100644
--- a/src/doc/macros.rst
+++ b/src/doc/macros.rst
@@ -192,6 +192,9 @@ The example will be expanded to:
           a: '5'
 
 
+Note, that you need to make sure that subsequent macro calls do not
+use the same top level key. Because later versions would overwrite previous
+ones. Here we used ``$macro_name`` to prevent that.
 
 
 Limitation