diff --git a/cogl/cogl.h b/cogl/cogl.h
index f15b2a95b..e639658da 100644
--- a/cogl/cogl.h
+++ b/cogl/cogl.h
@@ -258,13 +258,26 @@ cogl_frustum (float left,
  * @right: The coordinate for the right clipping plane
  * @bottom: The coordinate for the bottom clipping plane
  * @top: The coordinate for the top clipping plane
- * @near: The coordinate for the near clipping plane (may be negative if
+ * @near: The <b>distance</b> to the near clipping plane (negative if
  *        the plane is behind the viewer)
- * @far: The coordinate for the far clipping plane (may be negative if
+ * @far: The <b>distance</b> for the far clipping plane (negative if
  *       the plane is behind the viewer)
  *
- * Replaces the current projection matrix with a parallel projection
- * matrix.
+ * Replaces the current projection matrix with an orthographic projection
+ * matrix. See <xref linkend="cogl-ortho-matrix"/> to see how the matrix is
+ * calculated.
+ *
+ * <figure id="cogl-ortho-matrix">
+ *   <title></title>
+ *   <graphic fileref="cogl_ortho.png" format="PNG"/>
+ * </figure>
+ *
+ * <note>cogl_ortho copies the arguments from OpenGL's glOrtho even
+ * though they are unnecessarily confusing due to the z near and z far
+ * arguments actually being a "distance" from the origin, where
+ * negative values are behind the viewer, instead of coordinates for
+ * the z clipping planes which would have been consistent with the
+ * left, right bottom and top arguments.</note>
  *
  * Since: 1.0
  */
diff --git a/doc/reference/cogl/Makefile.am b/doc/reference/cogl/Makefile.am
index a066e445a..5b1d1fb5f 100644
--- a/doc/reference/cogl/Makefile.am
+++ b/doc/reference/cogl/Makefile.am
@@ -92,7 +92,8 @@ EXTRA_HFILES=
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
 HTML_IMAGES = \
-	fill-rule.png
+	fill-rule.png \
+	cogl_ortho.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
@@ -121,4 +122,5 @@ include $(top_srcdir)/gtk-doc.make
 # e.g. EXTRA_DIST += version.xml.in
 
 EXTRA_DIST += \
-	fill-rule.png
+	fill-rule.png \
+	cogl_ortho.png
diff --git a/doc/reference/cogl/cogl_ortho.png b/doc/reference/cogl/cogl_ortho.png
new file mode 100644
index 000000000..2c2a1fd20
Binary files /dev/null and b/doc/reference/cogl/cogl_ortho.png differ