diff --git a/.flake8 b/.flake8
@@ -94,6 +94,7 @@ per-file-ignores =
     tutorials/colors/colormap-manipulation.py: E402
     tutorials/intermediate/artists.py: E402
     tutorials/intermediate/constrainedlayout_guide.py: E402
+    tutorials/intermediate/gridspec.py: E402
     tutorials/intermediate/legend_guide.py: E402
     tutorials/intermediate/tight_layout_guide.py: E402
     tutorials/introductory/customizing.py: E501

diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst
@@ -23,8 +23,7 @@ Sophisticated subplot grid layout
 
 Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
 doing complex subplot layouts, featuring row and column spans and
-more.  See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial
-overview.
+more.  See :doc:`/tutorials/intermediate/gridspec` for a tutorial overview.
 
 .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png
    :target: ../../gallery/userdemo/demo_gridspec01.html

diff --git a/examples/lines_bars_and_markers/scatter_hist.py b/examples/lines_bars_and_markers/scatter_hist.py
@@ -88,8 +88,8 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # ----------------
 #
 # We may equally define a gridspec with unequal width- and height-ratios to
-# achieve desired layout. Also see the
-# :doc:`/tutorials/intermediate/arranging_axes` tutorial.
+# achieve desired layout. Also see the :doc:`/tutorials/intermediate/gridspec`
+# tutorial.
 
 # start with a square Figure
 fig = plt.figure(figsize=(8, 8))

diff --git a/examples/subplots_axes_and_figures/gridspec_and_subplots.py b/examples/subplots_axes_and_figures/gridspec_and_subplots.py
@@ -8,10 +8,7 @@
 and then remove the covered axes and fill the gap with a new bigger axes.
 Here we create a layout with the bottom two axes in the last column combined.
 
-To start with this layout (rather than removing the overlapping axes) use
-`~.pyplot.subplot_mosaic`.
-
-See also :doc:`/tutorials/intermediate/arranging_axes`.
+See also :doc:`/tutorials/intermediate/gridspec`.
 """
 
 import matplotlib.pyplot as plt

diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -5,10 +5,8 @@
 The `GridSpec` specifies the overall grid structure. Individual cells within
 the grid are referenced by `SubplotSpec`\s.
 
-Often, users need not access this module directly, and can use higher-level
-methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and
-`~.Figure.subfigures`. See the tutorial
-:doc:`/tutorials/intermediate/arranging_axes` for a guide.
+See the tutorial :doc:`/tutorials/intermediate/gridspec` for a comprehensive
+usage guide.
 """
 
 import copy