diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -1517,6 +1517,49 @@
 Similarly setting `WANT_OPEN_MOTIF_DEVEL` in [.filename]#make.conf# will add a
 dependency on package:x11-toolkits/open-motif-devel[]
 
+[[uses-mpi]]
+== `mpi`
+
+Possible arguments: `mpich` (default), `openmpi`
+
+Provide support for ports depending on `MPI`.
+
+If the `mpich` argument is provided a dependency on package:net/mpich[] is added
+to the port.
+
+If the `openmpi` argument is provided a dependency on package:net/openmpi[] is
+added to the port.
+
+The ports framework provides the following variables that can be read by the port:
+
+`MPI_LIBS`::
+Libraries needed to link programs using `MPI`.
+
+`MPI_CFLAGS`::
+Compiler flags necessary to build programs using `MPI`.
+
+`MPICC`::
+Location of the `mpicc` executable. Default: [.filename]#${MPI_HOME}/bin/mpicc#.
+
+`MPICXX`::
+Location of the `mpicxx` executable. Default: [.filename]#${MPI_HOME}/bin/mpicxx#.
+
+`MPIF90`::
+Location of the `mpif90` executable. Default: [.filename]#${MPI_HOME}/bin/mpif90#.
+
+`MPIFC`::
+Same as above.
+
+`MPI_HOME`::
+Installation directory of `MPI`. Defaults to `${LOCALBASE}` for `MPICH`.
+
+`MPIEXEC`::
+Location of the `mpiexec` executable. Default: [.filename]#${MPI_HOME}/bin/mpiexec#.
+
+`MPIRUN`::
+Location of the `mpirun` executable. Default: [.filename]#${MPI_HOME}/bin/mpirun#.
+
+
 [[uses-ncurses]]
 == `ncurses`