diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst
index 1c0bbde0d1d..80d94344507 100644
--- a/src/TwigComponent/doc/index.rst
+++ b/src/TwigComponent/doc/index.rst
@@ -337,6 +337,33 @@ You can even give the block default content. See
 :ref:`Passing HTML to Components via Block <embedded-components>`
 for more info.
 
+Composition vs Inheritance
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Symfony tend to follow the best pratice of the component architecture, so it's highly recommended to use Composition instead of Inheritance to reuse code betwen component (see: https://legacy.reactjs.org/docs/composition-vs-inheritance.html).
+
+Let's take an exemple. Some component don't know their children ahead of time. This is common for components like Alert or Dialog that represent generic “boxes”. We recommend you
+to use the block content to pass children directly into their output :
+
+.. code-block:: html+twig
+
+    <div class="alert">
+       {% block content %}
+       {% endblock %}
+    </div>
+
+This lets other components pass arbitrary children to them by nesting the elements :
+
+.. code-block:: html+twig
+
+    <twig:Alert>
+        <twig:Icon name="success"/> 
+        <p>Nice work!</p>
+    </twig:Alert>
+
+Anything inside the <twig:Alert>  tag gets passed into the Alert component as a content block. Since Alert renders {% block content %} inside a <div>, the passed elements appear in the final output.
+You can go deeper on the usage of block, on this part of the :ref:`documentation <embedded-components>`
+
 Fetching Services
 -----------------
 
@@ -670,6 +697,10 @@ You can also add more, named blocks:
         </twig:block>
     </twig:Alert>
 
+.. note::
+
+    Because your TwigComponent live inside his own specific context, you can't use the parent function inside the block of your component template.
+
 Render these in the normal way.
 
 .. code-block:: html+twig