diff --git a/doc/language-support.xml b/doc/language-support.xml
index def0de1d91f..798988274ec 100644
--- a/doc/language-support.xml
+++ b/doc/language-support.xml
@@ -341,7 +341,16 @@ twisted = buildPythonPackage {
   <para>By default <varname>doCheck = true</varname> is set and tests are run with
   <literal>${python.interpreter} setup.py test</literal> command in <varname>checkPhase</varname>.</para>
 
-  <para><varname>propagatedBuildInputs</varname> packages are propagated to user environment.</para>
+  <para><varname>propagatedBuildInputs</varname> packages are propagated to the user environment.</para>
+
+  <para>
+    As in Perl, dependencies on other Python packages can be specified in the
+    <varname>buildInputs</varname> and
+    <varname>propagatedBuildInputs</varname> attributes.  If something is
+    exclusively a build-time dependency, use
+    <varname>buildInputs</varname>; if it’s (also) a runtime dependency,
+    use <varname>propagatedBuildInputs</varname>.
+  </para>
 
   <para>
     By default <varname>meta.platforms</varname> is set to the same value