Problem

Most of the content of https://matplotlib.org/tutorials/introductory/lifecycle.html#a-note-on-the-object-oriented-api-vs-pyplot will not make sense to a user new matplotlib ( and likely new to python). The text makes several assumptions about the reader:

• They know what object oriented means
• They know what a state-based interface is
• They know what the Matlab interface is like
• They understand "we utilize an instance of axes.Axes in order to render visualizations on an instance of figure.Figure."
  • Doesn't pyplot also do this under the hood?

As a piece of anecdata I was fairly confused by all of this both years ago when I started using matplotlib and more recently when I started to make more complex and interactive matplotlib plots.

Suggested Improvement

Add deeper explanations/definitions for all the above bullet points. As well it would be great to expand on the note that simply says:

In general, try to use the object-oriented interface over the pyplot interface.

with a justification of that claim.

A related example is https://matplotlib.org/gallery/api/agg_oo_sgskip.html which could also use some more explanation or perhaps removal.