diff --git a/reference/xmlwriter/functions/xmlwriter-text.xml b/reference/xmlwriter/functions/xmlwriter-text.xml
index 67f6dc58cb..ee860ac434 100644
--- a/reference/xmlwriter/functions/xmlwriter-text.xml
+++ b/reference/xmlwriter/functions/xmlwriter-text.xml
@@ -34,6 +34,13 @@
      <listitem>
       <para>
        The contents of the text.
+       The characters <literal>&lt;</literal>, <literal>&gt;</literal>,
+       <literal>&amp;</literal> and <literal>"</literal> are written as
+       entity references (i.e. <literal>&amp;lt;</literal>, <literal>&amp;gt;</literal>,
+       <literal>&amp;amp;</literal> and <literal>&amp;quot;</literal>, respectively).
+       All other characters including <literal>&apos;</literal> are written literally.
+       To write the special XML characters literally, or to write literal entity references,
+       <function>xmlwriter_write_raw</function> has to be used.
       </para>
      </listitem>
     </varlistentry>