diff --git a/examples/lines_bars_and_markers/marker_reference.py b/examples/lines_bars_and_markers/marker_reference.py
index a6510d3bf049..3d73ddee94ab 100644
--- a/examples/lines_bars_and_markers/marker_reference.py
+++ b/examples/lines_bars_and_markers/marker_reference.py
@@ -13,6 +13,9 @@
   :doc:`/gallery/shapes_and_collections/marker_path`.
 
 For a list of all markers see also the `matplotlib.markers` documentation.
+
+For example usages see
+:doc:`/gallery/lines_bars_and_markers/scatter_star_poly`.
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/lines_bars_and_markers/scatter_star_poly.py b/examples/lines_bars_and_markers/scatter_star_poly.py
index 6dafbf27c832..690d7ae3944e 100644
--- a/examples/lines_bars_and_markers/scatter_star_poly.py
+++ b/examples/lines_bars_and_markers/scatter_star_poly.py
@@ -1,11 +1,11 @@
 """
-=================
-Scatter Star Poly
-=================
+===============
+Marker examples
+===============
 
-Create multiple scatter plots with different
-star symbols.
+Example with different ways to specify markers.
 
+For a list of all markers see also the `matplotlib.markers` documentation.
 """
 import numpy as np
 import matplotlib.pyplot as plt
@@ -13,28 +13,36 @@
 # Fixing random state for reproducibility
 np.random.seed(19680801)
 
-
 x = np.random.rand(10)
 y = np.random.rand(10)
 z = np.sqrt(x**2 + y**2)
 
-plt.subplot(321)
-plt.scatter(x, y, s=80, c=z, marker=">")
+fig, axs = plt.subplots(2, 3, sharex=True, sharey=True)
+
+# marker symbol
+axs[0, 0].scatter(x, y, s=80, c=z, marker=">")
+axs[0, 0].set_title("marker='>'")
 
-plt.subplot(322)
-plt.scatter(x, y, s=80, c=z, marker=(5, 0))
+# marker from TeX
+axs[0, 1].scatter(x, y, s=80, c=z, marker=r'$\alpha$')
+axs[0, 1].set_title(r"marker=r'\$\alpha\$'")
 
+# marker from path
 verts = np.array([[-1, -1], [1, -1], [1, 1], [-1, -1]])
-plt.subplot(323)
-plt.scatter(x, y, s=80, c=z, marker=verts)
+axs[0, 2].scatter(x, y, s=80, c=z, marker=verts)
+axs[0, 2].set_title("marker=verts")
 
-plt.subplot(324)
-plt.scatter(x, y, s=80, c=z, marker=(5, 1))
+# regular polygon marker
+axs[1, 0].scatter(x, y, s=80, c=z, marker=(5, 0))
+axs[1, 0].set_title("marker=(5, 0)")
 
-plt.subplot(325)
-plt.scatter(x, y, s=80, c=z, marker='+')
+# regular star marker
+axs[1, 1].scatter(x, y, s=80, c=z, marker=(5, 1))
+axs[1, 1].set_title("marker=(5, 1)")
 
-plt.subplot(326)
-plt.scatter(x, y, s=80, c=z, marker=(5, 2))
+# regular asterisk marker
+axs[1, 2].scatter(x, y, s=80, c=z, marker=(5, 2))
+axs[1, 2].set_title("marker=(5, 2)")
 
+plt.tight_layout()
 plt.show()
diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py
index ff9a64db810d..bab0d4a600b8 100644
--- a/lib/matplotlib/markers.py
+++ b/lib/matplotlib/markers.py
@@ -84,6 +84,7 @@
 
 * :doc:`/gallery/lines_bars_and_markers/marker_reference`
 * :doc:`/gallery/shapes_and_collections/marker_path`
+* :doc:`/gallery/lines_bars_and_markers/scatter_star_poly`
 
 
 .. |m00| image:: /_static/markers/m00.png