DOC: add hint

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