diff --git a/steps/src/main/xml/steps/replace.xml b/steps/src/main/xml/steps/replace.xml
index b72f789..1906923 100644
--- a/steps/src/main/xml/steps/replace.xml
+++ b/steps/src/main/xml/steps/replace.xml
@@ -5,9 +5,9 @@
          xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="c.replace">
 <title>p:replace</title>
 
-<para>The <code>p:replace</code> step replaces matching nodes in
-its primary input with the top-level node(s) of the
-<code>replacement</code> port's document.</para>
+<para>The <code>p:replace</code> step replaces matching nodes in its primary
+input with the content of the document that appears on the
+<port>replacement</port> port.</para>
 
 <p:declare-step type="p:replace">
    <p:input port="source" primary="true" content-types="xml html"/>
@@ -23,12 +23,13 @@ an attribute or a namespace nodes. </error> Multiple matches are allowed, in whi
 copies of the <port>replacement</port> document will occur.</para>
 
 <para>Every node in the primary input matching the specified
-pattern is replaced in the output by the top-level node(s)
+pattern is replaced in the output by the content
 of the <port>replacement</port> document. Only non-nested matches are
 replaced. That is, once a node is replaced, its descendants cannot
 be matched.</para>
 
-<para>If the document node is matched, the result is a text document.</para>
+<para>If the document node is matched, and the <port>replacement</port> document is a text document,
+the <port>result</port> is a text document.</para>
 
 <simplesect>
 <title>Document properties</title>