diff --git a/docs/library/index.rst b/docs/library/index.rst
index 7d4bb872cf..dc89766e2d 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -116,6 +116,19 @@ the following libraries.
    uctypes.rst
 
 
+Port-specific libraries
+-----------------------
+
+In some cases the following port/board-specific libraries have functions or
+classes similar to those in the :mod:`machine` library.  Where this occurs, the
+entry in the port specific library exposes hardware functionality unique to
+that platform.
+
+To write portable code use functions and classes from the :mod:`machine` module.
+To access platform-specific hardware use the appropriate library, e.g.
+:mod:`pyb` in the case of the Pyboard.
+
+
 Libraries specific to the pyboard
 ---------------------------------