diff --git a/doc/api/index.rst b/doc/api/index.rst
index 644842ee70ae..1b098009faed 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -1,82 +1,44 @@
 API Reference
 =============
 
-When using the library you will typically create
-:doc:`Figure <figure_api>` and :doc:`Axes <axes_api>` objects and
-call their methods to add content and modify the appearance.
+Matplotlib interfaces
+---------------------
 
-- :mod:`matplotlib.figure`: axes creation, figure-level content
-- :mod:`matplotlib.axes`: most plotting methods, Axes labels, access to axis
-  styling, etc.
+Matplotlib provides two different interfaces:
 
-Example: We create a Figure ``fig`` and Axes ``ax``. Then we call
-methods on them to plot data, add axis labels and a figure title.
+- **Axes interface**: create a `.Figure` and one or more `~.axes.Axes` objects
+  (typically using `.pyplot.subplots`), then *explicitly* use methods on these objects
+  to add data, configure limits, set labels etc.
+- **pyplot interface**: consists of functions in the `.pyplot` module. Figure and Axes
+  are manipulated through these functions and are only *implicitly* present in the
+  background.
 
-.. plot::
-   :include-source:
-   :align: center
+See :ref:`api_interfaces` for a more detailed description of both and their recommended
+use cases.
 
-   import matplotlib.pyplot as plt
-   import numpy as np
+.. grid:: 1 1 2 2
+    :padding: 0 0 1 1
 
-   x = np.arange(0, 4, 0.05)
-   y = np.sin(x*np.pi)
+    .. grid-item-card::
 
-   fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True)
-   ax.plot(x, y)
-   ax.set_xlabel('t [s]')
-   ax.set_ylabel('S [V]')
-   ax.set_title('Sine wave')
-   fig.set_facecolor('lightsteelblue')
+        **Axes interface** (object-based, explicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+        API:
 
+        - `~.pyplot.subplots`: create Figure and Axes
+        - :mod:`~matplotlib.axes`: add data, limits, labels etc.
+        - `.Figure`: for figure-level methods
 
-.. _usage_patterns:
+    .. grid-item-card::
 
-Usage patterns
---------------
+        **pyplot interface** (function-based, implicit)
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Below we describe several common approaches to plotting with Matplotlib.  See
-:ref:`api_interfaces` for an explanation of the trade-offs between the supported user
-APIs.
+        API:
 
+        - `matplotlib.pyplot`
 
-The explicit API
-^^^^^^^^^^^^^^^^
-
-At its core, Matplotlib is an object-oriented library. We recommend directly
-working with the objects if you need more control and customization of your
-plots.
-
-In many cases you will create a `.Figure` and one or more
-`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
-on these objects. However, it's also possible to create `.Figure`\ s
-explicitly (e.g. when including them in GUI applications).
-
-Further reading:
-
-- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
-  plotting functions.
-- Most of the :ref:`examples <examples-index>` use the object-oriented approach
-  (except for the pyplot section)
-
-
-The implicit API
-^^^^^^^^^^^^^^^^
-
-`matplotlib.pyplot` is a collection of functions that make
-Matplotlib work like MATLAB. Each pyplot function makes some change to a
-figure: e.g., creates a figure, creates a plotting area in a figure, plots
-some lines in a plotting area, decorates the plot with labels, etc.
-
-`.pyplot` is mainly intended for interactive plots and simple cases of
-programmatic plot generation.
-
-Further reading:
-
-- The `matplotlib.pyplot` function reference
-- :ref:`pyplot_tutorial`
-- :ref:`Pyplot examples <pyplots_examples>`
 
 .. _api-index:
 
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
index a5b9abebffe9..684021b2e977 100644
--- a/lib/matplotlib/pylab.py
+++ b/lib/matplotlib/pylab.py
@@ -1,6 +1,6 @@
 """
 `pylab` is a historic interface and its use is strongly discouraged. The equivalent
-replacement is `matplotlib.pyplot`.  See :ref:` api_interfaces` for a full overview
+replacement is `matplotlib.pyplot`.  See :ref:`api_interfaces` for a full overview
 of Matplotlib interfaces.
 
 `pylab` was designed to support a MATLAB-like way of working with all plotting related
@@ -14,7 +14,7 @@
    `numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into
    the global namespace.
 
-   Such a pattern is nowadays considered bad practice, as it clutters the global
+   Such a pattern is considered bad practice in modern python, as it clutters the global
    namespace. Even more severely, in the case of `pylab`, this will overwrite some
    builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which
    can lead to unexpected behavior.