diff --git a/README.rst b/README.rst
index 32beed9f2e..8f3519f819 100644
--- a/README.rst
+++ b/README.rst
@@ -41,6 +41,12 @@ Various manuals are in subdirectories of the ``doc/`` directory.
 Guides
 ------
 
+Some pre-requisites are needed to build the guides. If you are using a Linux
+operating system you can generate a report of missing local requirements with
+the ``bindep`` command::
+
+    $ tox -e bindep
+
 All guides are in the RST format. You can use ``tox`` to prepare
 virtual environment and build all guides (HTML only):
 
@@ -63,12 +69,6 @@ To build a specific guide with a PDF file, add a ``-pdf`` option like::
 The generated PDF file will be copied to the root directory of the
 generated HTML documentation.
 
-To install all requirements to execute the commands above, on Linux you can
-check the output of the ``bindep`` command. This tool reports missing
-requirements for all build targets::
-
-    $ tox -e bindep
-
 If you get this message `make: xelatex: No such file or directory` it means
 your local environment does not have LaTeX installed. Read `Getting LaTeX
  <https://www.latex-project.org/get/>`_ for instructions.
diff --git a/doc/contributor-guide/source/docs-builds.rst b/doc/contributor-guide/source/docs-builds.rst
index f7021aa8ee..efa5dc816f 100644
--- a/doc/contributor-guide/source/docs-builds.rst
+++ b/doc/contributor-guide/source/docs-builds.rst
@@ -18,6 +18,12 @@ automation of test activities.
 Install dependencies for building documentation
 -----------------------------------------------
 
+.. note::
+
+   You cannot run :command:`tox -e bindep` on Mac OS X as it uses a Linux tool
+   to parse the information. `Issue logged here
+   <https://storyboard.openstack.org/#!/story/2000888>`_.
+
 * On Ubuntu or Debian:
 
   .. code-block:: console