diff --git a/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md b/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
index 5b8f886623..a24a512cf7 100644
--- a/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
+++ b/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
@@ -127,6 +127,18 @@ represented by our 1.0 implementation as strings, meaning that `@BeginLine > "1"
 worked ---that's not the case in 2.0 mode.
    * <code>@ArgumentCount > <b style="color:red">'</b>1<b style="color:red">'</b></code> &rarr; `@ArgumentCount > 1`
 
+* In XPath 1.0, the expression `/Foo` matches the *children* of the root named `Foo`.
+In XPath 2.0, that expression matches the root, if it is named `Foo`. Consider the following tree:
+```java
+Foo
+└─ Foo
+└─ Foo
+```
+Then `/Foo` will match the root in XPath 2, and the other nodes (but not the root) in XPath 1.
+See eg [an issue caused by this](https://github.com/pmd/pmd/issues/1919#issuecomment-512865434) in Apex,
+with nested classes.
+
+
 ## Rule properties
 
 **See [Defining rule properties](pmd_userdocs_extending_defining_properties.html#for-xpath-rules)**