I've been helping a fairly new Python user (an astronomer using numpy/scipy/matplotlib) in my office get up to speed with matplotlib and thought I'd pass on a couple of small thoughts about the documentation which we think would make life clearer for new users. I'm putting this out for discussion, because it may be totally off-the-mark. On the other hand, it may point to some easy changes to make things clearer for new users.
First, I think that a new user, presented with the mpl homepage, reads the intro on that page, then perhaps clicks through to either the pyplot, examples, or gallery pages. They may take example code from examples or gallery and modify them for their own plots, but they will at some point be referencing the pyplot page (this is also my most-visited page on the site). The matplotlib.pyplot page would really benefit from a few introductory paragraphs or even a single sentence with a link to the relevant section in the docs, explaining what the relationship of pyplot is to the other parts of mpl. Specifically, I think confusion arises because the explanation about the stateful nature of the pyplot interface is (I think) first mentioned at the start of the pyplot tutorial page, and is perhaps not emphasized enough. It may also be worth stating somewhere in the front-page mpl intro that it is recommended that new users do the pyplot tutorial. The signatures that a new user sees are full of *args and **kwargs which is confusing for the new user. There is an explanation in the coding guide so perhaps another paragraph or sentence+link to this would help, but I think it's probably not a good idea to be directing new users into the coding guide. I know about the history of this and I gather that most or all of the args are actually tabulated in the documentation now, but new users don't necessarily know what *args and **kwargs mean. I think there's still a general lack of consistency in the pyplot docs related to this. Some docstrings have the call signature shown, with default values shown. It's confusing that some kwargs have explicit descriptions and appear in the call signature whereas others are just "additional kwargs". This split seems to me to be exposing the underlying implementation of the function to the user. I don't know whether there is logic behind this. The final area of confusion is to do with jargon, as this seems to creep into examples and list discussions. The introduction to the Artist Tutorial is quite useful for understanding mpl's plotting model. However, for the new user, it is pretty much impenetrable due to the jargon and references to other libraries and coding concepts that a new user doesn't need to know. I think a gentler description of mpl's plotting model in the introduction or in a standalone small chapter would be helpful for new users. Gary R. ------------------------------------------------------------------------------ Download Intel® Parallel Studio Eval Try the new software tools for yourself. Speed compiling, find bugs proactively, and fine-tune applications for parallel performance. See why Intel Parallel Studio got high marks during beta. http://p.sf.net/sfu/intel-sw-dev _______________________________________________ Matplotlib-users mailing list Matplotlib-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-users
