diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index b876bc3115..e265aa94bd 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2791,6 +2791,39 @@
task of recipe "b".
This means anything that recipe "b" puts into sysroot
is available when recipe "a" is configuring itself.
+
+ Notes
+
+
+ DEPENDS is a list of
+ recipe names.
+ Or, to be more precise, it is a list of
+ PROVIDES
+ names, which usually match recipe names.
+ Putting a package name such as "foo-dev" in
+ DEPENDS does not make
+ sense.
+ Use "foo" instead, as this will put files
+ from all the packages that make up "foo" -
+ including those from "foo-dev" - into the
+ sysroot.
+
+
+ Counter intuitively,
+ DEPENDS is often necessary
+ even for recipes that install precompiled
+ components.
+ For example, if "libfoo" is a precompiled
+ library that links against "libbar", then
+ linking against "libfoo" requires both "libfoo"
+ and "libbar" to be available in the sysroot.
+ Without a DEPENDS from the
+ recipe that installs "libfoo" to the recipe
+ that installs "libbar", other recipes might
+ fail to link against "libfoo".
+
+
+