diff --git a/.flake8 b/.flake8
index 2754bc04e4c4..07229a94811c 100644
--- a/.flake8
+++ b/.flake8
@@ -146,6 +146,7 @@ per-file-ignores =
     examples/lines_bars_and_markers/joinstyle.py: E402
     examples/lines_bars_and_markers/scatter_piecharts.py: E402
     examples/lines_bars_and_markers/span_regions.py: E402
+    examples/lines_bars_and_markers/step_demo.py: E402
     examples/misc/agg_buffer.py: E402
     examples/misc/anchored_artists.py: E501
     examples/misc/contour_manual.py: E501
diff --git a/examples/lines_bars_and_markers/step_demo.py b/examples/lines_bars_and_markers/step_demo.py
index 35da17e49319..12006b197e53 100644
--- a/examples/lines_bars_and_markers/step_demo.py
+++ b/examples/lines_bars_and_markers/step_demo.py
@@ -3,30 +3,42 @@
 Step Demo
 =========
 
-Example step plots.
+This example demonstrates the use of `.pyplot.step` for piece-wise constant
+curves. In particular, it illustrates the effect of the parameter *where*
+on the step position.
+
+The circular markers created with `.pyplot.plot` show the actual data
+positions so that it's easier to see the effect of *where*.
+
 """
 import numpy as np
-from numpy import ma
 import matplotlib.pyplot as plt
 
-x = np.arange(1, 7, 0.4)
-y0 = np.sin(x)
-y = y0.copy() + 2.5
+x = np.arange(14)
+y = np.sin(x / 2)
 
-plt.step(x, y, label='pre (default)')
+plt.step(x, y + 2, label='pre (default)')
+plt.plot(x, y + 2, 'C0o', alpha=0.5)
 
-y -= 0.5
-plt.step(x, y, where='mid', label='mid')
+plt.step(x, y + 1, where='mid', label='mid')
+plt.plot(x, y + 1, 'C1o', alpha=0.5)
 
-y -= 0.5
 plt.step(x, y, where='post', label='post')
+plt.plot(x, y, 'C2o', alpha=0.5)
 
-y = ma.masked_where((y0 > -0.15) & (y0 < 0.15), y - 0.5)
-plt.step(x, y, label='masked (pre)')
-
-plt.legend()
-
-plt.xlim(0, 7)
-plt.ylim(-0.5, 4)
-
+plt.legend(title='Parameter where:')
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.step
+matplotlib.pyplot.step