diff --git a/docs/reference/mapping/types/parent-join.asciidoc b/docs/reference/mapping/types/parent-join.asciidoc
index 048e866d03b..ad33205650d 100644
--- a/docs/reference/mapping/types/parent-join.asciidoc
+++ b/docs/reference/mapping/types/parent-join.asciidoc
@@ -32,7 +32,7 @@ PUT my_index
 
 To index a document with a join, the name of the relation and the optional parent
 of the document must be provided in the `source`.
-For instance the following creates two parent documents in the `question` context:
+For instance the following example creates two `parent` documents in the `question` context:
 
 [source,js]
 --------------------------------------------------
@@ -85,8 +85,7 @@ must be added in the `_source`.
 WARNING: It is required to index the lineage of a parent in the same shard so you must
 always route child documents using their greater parent id.
 
-For instance the following index two children documents pointing to the same parent `1`
-with a `routing` value equals to the `id` of the parent:
+For instance the following example shows how to index two `child` documents:
 
 [source,js]
 --------------------------------------------------
@@ -111,7 +110,7 @@ PUT my_index/doc/4?routing=1&refresh
 // CONSOLE
 // TEST[continued]
 
-<1> This child document must be on the same shard than its parent
+<1> The routing value is mandatory because parent and child documents must be indexed on the same shard
 <2> `answer` is the name of the join for this document
 <3> The parent id of this child document