diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 1c0864d87..b16a6272c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8735,6 +8735,24 @@ system and gives an overview of their function and contents.
 
          RPROVIDES:${PN} = "widget-abi-2"
 
+      An alias can also carry a version, using the same syntax as
+      :term:`RDEPENDS` with the ``=`` operator::
+
+         RPROVIDES:${PN} = "widget-abi (= 2)"
+
+      Other packages can then depend on a range of versions of the alias,
+      which an alias with the version in its name cannot express::
+
+         RDEPENDS:${PN} = "widget-abi (>= 2)"
+
+      .. note::
+
+         Only the :ref:`ref-classes-package_rpm` class writes the version
+         into the package metadata. The :ref:`ref-classes-package_ipk` and
+         :ref:`ref-classes-package_deb` classes drop it and provide the bare
+         alias, so a versioned dependency on the alias cannot be relied upon
+         with those package formats.
+
    :term:`RRECOMMENDS`
       A list of packages that extends the usability of a package being
       built. The package being built does not depend on this list of