> 1) establish by example the coding conventions for using the matplotlib library

Exactly my reason for brining this up. 
I hold neither ```fig.add_subplot(111)``` nor ```plt.subplots()``` close to my heart - it seems to me that we do not want to hide from the fact that the primary plotting area inside a figure is an ```Axes``` (whether you like the name or not) so why, for newcomers reading the examples, do we not show their creation with the very helpful pyplot ```axes``` function? The matlab argument is good, indeed perhaps we could have a section introducing matplotlib for matlab users, but I don't think it should be our main driver for API design...

> Making the examples familiar to them, but yet also following best coding practices of matplotlib is a tricky balance

Agreed.