diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index d66fe1b0c6..4fb1f64646 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9568,6 +9568,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
      PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
      PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
                     </literallayout>
+                    <note>
+                        If you set <filename>PREFERRED_PROVIDER</filename>
+                        for a <filename>virtual/*</filename> item, then any
+                        recipe that
+                        <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
+                        that item that is not selected by
+                        <filename>PREFERRED_PROVIDER</filename> is prevented
+                        from building, which is usually desirable since this
+                        mechanism is designed to select between mutually
+                        exclusive alternative providers.
+                    </note>
                 </para>
             </glossdef>
         </glossentry>