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.
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:
Ryan
ยทยทยท
On Sun, Apr 18, 2010 at 12:10 AM, Gary Ruben <gruben@...636...> 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.
--
Ryan May
Graduate Research Assistant
School of Meteorology
University of Oklahoma