diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
index 09662f78c8..a4abad5d20 100644
--- a/docs/formatcaps.html.in
+++ b/docs/formatcaps.html.in
@@ -51,7 +51,10 @@
       <dt><code>topology</code></dt>
       <dd>This element embodies the host internal topology. Management
       applications may want to learn this information when orchestrating new
-      guests - e.g. due to reduce inter-NUMA node transfers.</dd>
+      guests - e.g. due to reduce inter-NUMA node transfers. Note that the
+      <code>sockets</code> value reported here is per-NUMA-node; this is in
+      contrast to the value given in domain definitions, which is interpreted
+      as a total number of sockets for the domain.</dd>
 
       <dt><code>secmodel</code></dt>
       <dd>To find out default security labels for different security models you
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index e492532004..9652e97eec 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -1489,12 +1489,12 @@ In case no restrictions need to be put on CPU model and its features, a simpler
    The ``topology`` element specifies requested topology of virtual CPU provided
    to the guest. Four attributes, ``sockets``, ``dies``, ``cores``, and
    ``threads``, accept non-zero positive integer values. They refer to the
-   number of CPU sockets per NUMA node, number of dies per socket, number of
-   cores per die, and number of threads per core, respectively. The ``dies``
-   attribute is optional and will default to 1 if omitted, while the other
-   attributes are all mandatory. Hypervisors may require that the maximum number
-   of vCPUs specified by the ``cpus`` element equals to the number of vcpus
-   resulting from the topology.
+   total number of CPU sockets, number of dies per socket, number of cores per
+   die, and number of threads per core, respectively. The ``dies`` attribute is
+   optional and will default to 1 if omitted, while the other attributes are all
+   mandatory. Hypervisors may require that the maximum number of vCPUs specified
+   by the ``cpus`` element equals to the number of vcpus resulting from the
+   topology.
 ``feature``
    The ``cpu`` element can contain zero or more ``feature`` elements used to
    fine-tune features provided by the selected CPU model. The list of known