On Sun, Apr 18, 2010 at 12:10 AM, Gary Ruben <gru...@bigpond.net.au> wrote: > 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.
The documentation exists to help the users, so if you're having trouble with them, the docs probably *are* lacking. I know I'm not likely to get to this any time soon however, so patches are welcome. :) If you're interested, the docs live here: http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/doc/ Ryan -- Ryan May Graduate Research Assistant School of Meteorology University of Oklahoma ------------------------------------------------------------------------------ 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
