API Documentation usability

Development matplotlib-devel
1

At risk of sounding defensive, all of the core developers are working mpl on a mostly volunteer basis and only have so much bandwidth. This leads to both thing falling through the cracks (we have close to 100 open PRs, that is way too many) and major re-factors (which every one agrees should be done) not being done.

I fully agree the docs are less than ideal. Some of what you suggest is already on the radar (giving each plotting function it’s own page) and a complete overhaul of the webpage is (very slowly) in the works. http://matplotlib.org/api/pyplot_summary.html covers some of the use-case of the table of contents.

The reason that plotting methods appear in both Axes and in pyplot is due to the layered design of mpl. The actual plotting logic is implemented as methods on the Axes object and the pyplot layer provides a MATLAB-like state machine to make plotting convenient. The fact that you have the same functions in both places is a feature, not a bug ;). We don’t use decorators for pyplot.py because that code pre-dates fully functional decorators.

This part of the design, the plotting logic being methods on the Axes object, is why the Axes class is so large and I do not think can be broken up in any sensible way (at the code level) short of abandoning it all together and moving to modules of functions with signatures like fun(ax, data, style). This has been discussed, but it is a HUGE change to the architecture of the library and we are (rightly) moving slowly on it. MPL is a widely used mature library which means one of the most important things we have to do is not break existing user code.

Providing human curation to the docs (a-la numpy) would be great, the main problem is time. The core-devs (who seem to enjoy very drudgery) are already over whelmed, ‘update the docs’ is not really an exciting thing that new contributors will jump on, and fixing the docs does require a good deal of familiarity with the library (so you know where the docs are wrong/misleading/missing!).

@Fabio That bit of the already seems pretty modular, but I am not super familiar with it. What would you change?

If anyone wants to help with MEP10 that would be great!

Tom

···

On Mon Feb 16 2015 at 7:02:13 AM Fabio Zanini <fabio.zanini@…1225…> wrote:

Dear Sebastian,

I agree with your impression. I made a pull request for some axis

functionality (logit scales) and the PR got lost. I am convinced that:

  1. working on things like axes, ticker, scales, locators would be a lot

easier with a little refactoring of the code

  1. with a more modular codebase, my PR would be accepted by now, instead

of living in limbo waiting to be forgotten.

So I am in general in favour of your proposal.

See also: https://github.com/matplotlib/matplotlib/pull/3753

Cheers,

Fabio

PS: if Thomas or anybody else is still willing to accept my PR itself,

I’d be in favour too. But please do not make me rebase another 3 times

before that :wink:

On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:

I’m a newcomer to the MPL code, and getting an overview is not easy.

Especially the API part of the documentation [1] has a lot of room for

improvement. The functionality of the MPL sources seems to be

scattered quite loosely among the sources and their structure is

directly mirrored in the doc. Some observations:

  1. Many functions like quiver() or bar() are in multiple places

(pyplot and axes)

  1. Some entries (like axes) are enormous, making them very hard to use

to get an overview

  1. The API start page is just a lose list of classes, without

indication what’s inside

Ideally I feel like the code itself should be organized in smaller

chunks, but that’s probably unrealistic. A quick improvement for 2.

could be to add a “table of contents” at the top of every class

documentation. For axes, that could work like [2] and look like [3].

Thoughts? I wanted to test the waters before making pull requests.

Another way could be to organize the documentation not by classes, but

by functionality. The Numpy docs [4] seem much more usable in that

regard. That’ll be less automatic of course but could help with

observation 3.

I’ve also found the Mep10 [5] on the Wiki with many good ideas, but

not sure if that lead somewhere.

Sebastian

[1] http://matplotlib.org/api/index.html

[2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1

[3] http://i.imgur.com/d1uTjfS.png

[4] http://docs.scipy.org/doc/numpy/reference/

[5] https://github.com/matplotlib/matplotlib/wiki/Mep10

Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server

from Actuate! Instantly Supercharge Your Business Reports and Dashboards

with Interactivity, Sharing, Native Excel Exports, App Integration & more

Get technology previously reserved for billion-dollar corporations, FREE

http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk

Matplotlib-devel mailing list

Matplotlib-devel@…1041…sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server

from Actuate! Instantly Supercharge Your Business Reports and Dashboards

with Interactivity, Sharing, Native Excel Exports, App Integration & more

Get technology previously reserved for billion-dollar corporations, FREE

http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk_______________________________________________

Matplotlib-devel mailing list

Matplotlib-devel@…1041…sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

2

Dear Thomas,

Finally got some time to reply about the docs. My main point is not
about the API docs themselves, although they would need some tuning à la
MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am
considering an issue with the non-API part of the docs, i.e. the user
guide, tutorial, and website.

MY OLD PROBLEM WITH THE DOCS

Now I am more experienced with mpl so I just read the API docs and
figure my way through, but at the beginning I remember that whenever I
was wondering about something I would quickly end up in either of two
places:

- the pyplot API page: http://matplotlib.org/api/pyplot_api.html

This is a giant blob of a page and takes several seconds just to load.
It's lacking any kind of menu or navigation help, just the whole docs
straight out - alphabetical order - and bam!

- stackoverflow

Here people give practical suggestions, but they are inconsistent (some
use pyplot, some axes methods, sometimes even more low-level code). I
mean, it does work, but it's messy and not very instructive for newbies
(imagine learning say chemistry from stackoverflow, not fun uh?)

HOW TO MAKE IT BETTER

This one's harder, but I'd have a couple of ideas:

1. better home page

The beginner's guide should be accessible from the home page in ONE
click, possibly highlighted in a frame or so. It currently takes 3
clicks on small text hyperlinks to get to some introduction, the pyplot
tutorial:

HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL

(and it's not even the first link on those pages). Some quick visual
snippet (possibly interactive e.g. an IPython notebook?) and maybe a
video tutorial like golang would be helpful:

http://golang.org/

2. More navigation support on the pyplot API page

I realize API docs need to be somewhat stiff in order to make sure you
find what you're looking for (alphabetical order and so), but some
side-menu, quick example, or highlighting of the most common items
(plot, scatter) would be useful. I've read the acorr API docs 100 times
by now, and never, ever used it :stuck_out_tongue_winking_eye:

3. clear presentation of the protagonist (Axes)

As far as I understand, the main object for the user is the Axes class.
For instance, does the code below look familiar to anyone?

ax.plot(x, y)
ax.scatter(x, y)
ax.set_xscale('log')
ax.set_xlabel('My x axis')
ax.set_xticks(...)
ax.legend()
ax.set_title('My title')
ax.grid(True)

Nonetheless, this kind of Axes-based coding is not even mentioned in the
beginner's guide. You may now think it's in the advanced guide but, no!
- the advanced guide only talks about "Artists" in general, not the Axes
in particular: "Artist tutorial", "Customizing your objects", etc.
I am not criticizing past mainteners for this organization, but I would
support a more Axes-centric tutorial in the beginner's guide.

As of the time issue, it's the usual problem, nobody wants to do the
docs because they are boring. It's true, it's a bit boring. But that
also depends a bit: writing API docs can be boring, but writing a
tutorial for newbies can be fun!

Cheers,
Fabio

3

This is excellent insight! It should be fairly trivial to fix points 1 and 2, and I agree that it would make the page much more inviting to newcomers.

Point 3 would take some time. I had never noticed that before. Personally, I think the issue about documentation isn’t that it is boring (I actually find them interesting), it is that by the time one gets into a project to actually start contributing, you become immune to the deficiencies in the documentation. Insights like these from newcomers are like gold to those of us who have been around for a while.

Feel free to either create some pull requests to address some of these points, or at least file some bug reports so that we don’t completely forget this. I may even be able to pick up some of it once my book finalizes for printing in the next week or two.

Cheers!

Ben Root

···

On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini <fabio.zanini@…1225…> wrote:

Dear Thomas,

Finally got some time to reply about the docs. My main point is not

about the API docs themselves, although they would need some tuning à la

MEP10. Rather, as Sebastian’s doubts about pyplot/axes shows, I am

considering an issue with the non-API part of the docs, i.e. the user

guide, tutorial, and website.

MY OLD PROBLEM WITH THE DOCS

Now I am more experienced with mpl so I just read the API docs and

figure my way through, but at the beginning I remember that whenever I

was wondering about something I would quickly end up in either of two

places:

This is a giant blob of a page and takes several seconds just to load.

It’s lacking any kind of menu or navigation help, just the whole docs

straight out - alphabetical order - and bam!

  • stackoverflow

Here people give practical suggestions, but they are inconsistent (some

use pyplot, some axes methods, sometimes even more low-level code). I

mean, it does work, but it’s messy and not very instructive for newbies

(imagine learning say chemistry from stackoverflow, not fun uh?)

HOW TO MAKE IT BETTER

This one’s harder, but I’d have a couple of ideas:

  1. better home page

The beginner’s guide should be accessible from the home page in ONE

click, possibly highlighted in a frame or so. It currently takes 3

clicks on small text hyperlinks to get to some introduction, the pyplot

tutorial:

HOME → DOCS → BEGINNER’S GUIDE → PYPLOT TUTORIAL

(and it’s not even the first link on those pages). Some quick visual

snippet (possibly interactive e.g. an IPython notebook?) and maybe a

video tutorial like golang would be helpful:

http://golang.org/

  1. More navigation support on the pyplot API page

I realize API docs need to be somewhat stiff in order to make sure you

find what you’re looking for (alphabetical order and so), but some

side-menu, quick example, or highlighting of the most common items

(plot, scatter) would be useful. I’ve read the acorr API docs 100 times

by now, and never, ever used it :stuck_out_tongue_winking_eye:

  1. clear presentation of the protagonist (Axes)

As far as I understand, the main object for the user is the Axes class.

For instance, does the code below look familiar to anyone?

ax.plot(x, y)

ax.scatter(x, y)

ax.set_xscale(‘log’)

ax.set_xlabel(‘My x axis’)

ax.set_xticks(…)

ax.legend()

ax.set_title(‘My title’)

ax.grid(True)

Nonetheless, this kind of Axes-based coding is not even mentioned in the

beginner’s guide. You may now think it’s in the advanced guide but, no!

  • the advanced guide only talks about “Artists” in general, not the Axes

in particular: “Artist tutorial”, “Customizing your objects”, etc.

I am not criticizing past mainteners for this organization, but I would

support a more Axes-centric tutorial in the beginner’s guide.

As of the time issue, it’s the usual problem, nobody wants to do the

docs because they are boring. It’s true, it’s a bit boring. But that

also depends a bit: writing API docs can be boring, but writing a

tutorial for newbies can be fun!

Cheers,

Fabio

Dive into the World of Parallel Programming The Go Parallel Website, sponsored

by Intel and developed in partnership with Slashdot Media, is your hub for all

things parallel software development, from weekly thought leadership blogs to

news, videos, case studies, tutorials and more. Take a look and join the

conversation now. http://goparallel.sourceforge.net/

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

4

Hi Ben,

Well, excellent or not I just hope it helps a bit. I can put some effort
if people agree that this is useful, though I am quite busy at the
moment. Who's currently actually managing the website?

Thx!
F

···

On 03/03/2015 21:33, Benjamin Root wrote:

This is excellent insight! It should be fairly trivial to fix points 1
and 2, and I agree that it would make the page much more inviting to
newcomers.

Point 3 would take some time. I had never noticed that before.
Personally, I think the issue about documentation isn't that it is
boring (I actually find them interesting), it is that by the time one
gets into a project to actually start contributing, you become immune to
the deficiencies in the documentation. Insights like these from
newcomers are like gold to those of us who have been around for a while.

Feel free to either create some pull requests to address some of these
points, or at least file some bug reports so that we don't completely
forget this. I may even be able to pick up some of it once my book
finalizes for printing in the next week or two.

Cheers!
Ben Root

On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini > <fabio.zanini@...1225... <mailto:fabio.zanini@…1225…>> > wrote:

    Dear Thomas,

    Finally got some time to reply about the docs. My main point is not
    about the API docs themselves, although they would need some tuning à la
    MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am
    considering an issue with the non-API part of the docs, i.e. the user
    guide, tutorial, and website.

    MY OLD PROBLEM WITH THE DOCS

    Now I am more experienced with mpl so I just read the API docs and
    figure my way through, but at the beginning I remember that whenever I
    was wondering about something I would quickly end up in either of two
    places:

    - the pyplot API page: http://matplotlib.org/api/pyplot_api.html

    This is a giant blob of a page and takes several seconds just to load.
    It's lacking any kind of menu or navigation help, just the whole docs
    straight out - alphabetical order - and bam!

    - stackoverflow

    Here people give practical suggestions, but they are inconsistent (some
    use pyplot, some axes methods, sometimes even more low-level code). I
    mean, it does work, but it's messy and not very instructive for newbies
    (imagine learning say chemistry from stackoverflow, not fun uh?)

    HOW TO MAKE IT BETTER

    This one's harder, but I'd have a couple of ideas:

    1. better home page

    The beginner's guide should be accessible from the home page in ONE
    click, possibly highlighted in a frame or so. It currently takes 3
    clicks on small text hyperlinks to get to some introduction, the pyplot
    tutorial:

    HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL

    (and it's not even the first link on those pages). Some quick visual
    snippet (possibly interactive e.g. an IPython notebook?) and maybe a
    video tutorial like golang would be helpful:

    http://golang.org/

    2. More navigation support on the pyplot API page

    I realize API docs need to be somewhat stiff in order to make sure you
    find what you're looking for (alphabetical order and so), but some
    side-menu, quick example, or highlighting of the most common items
    (plot, scatter) would be useful. I've read the acorr API docs 100 times
    by now, and never, ever used it :stuck_out_tongue_winking_eye:

    3. clear presentation of the protagonist (Axes)

    As far as I understand, the main object for the user is the Axes class.
    For instance, does the code below look familiar to anyone?

    ax.plot(x, y)
    ax.scatter(x, y)
    ax.set_xscale('log')
    ax.set_xlabel('My x axis')
    ax.set_xticks(...)
    ax.legend()
    ax.set_title('My title')
    ax.grid(True)

    Nonetheless, this kind of Axes-based coding is not even mentioned in the
    beginner's guide. You may now think it's in the advanced guide but, no!
    - the advanced guide only talks about "Artists" in general, not the Axes
    in particular: "Artist tutorial", "Customizing your objects", etc.
    I am not criticizing past mainteners for this organization, but I would
    support a more Axes-centric tutorial in the beginner's guide.

    As of the time issue, it's the usual problem, nobody wants to do the
    docs because they are boring. It's true, it's a bit boring. But that
    also depends a bit: writing API docs can be boring, but writing a
    tutorial for newbies can be fun!

    Cheers,
    Fabio

    ------------------------------------------------------------------------------
    Dive into the World of Parallel Programming The Go Parallel Website,
    sponsored
    by Intel and developed in partnership with Slashdot Media, is your
    hub for all
    things parallel software development, from weekly thought leadership
    blogs to
    news, videos, case studies, tutorials and more. Take a look and join the
    conversation now. http://goparallel.sourceforge.net/
    _______________________________________________
    Matplotlib-devel mailing list
    Matplotlib-devel@lists.sourceforge.net
    <mailto:Matplotlib-devel@lists.sourceforge.net>
    matplotlib-devel List Signup and Options

5

The website is generated by sphinx from the docstrings and other components in the doc/ directory of the matplotlib project. The file for the home page can be found:
https://github.com/matplotlib/matplotlib/blob/master/doc/_templates/index.html

By the way, the file for the “Documenting mpl” page is here:
https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst

And, like I said, even if you don’t get around to actually making any changes, at the very least, I would file these issues as “bugs” to our issue tracker.

Cheers!

Ben Root

···

On Tue, Mar 3, 2015 at 4:40 PM, Fabio Zanini <fabio.zanini@…1225…> wrote:

Hi Ben,

Well, excellent or not I just hope it helps a bit. I can put some effort

if people agree that this is useful, though I am quite busy at the

moment. Who’s currently actually managing the website?

Thx!

F

On 03/03/2015 21:33, Benjamin Root wrote:

This is excellent insight! It should be fairly trivial to fix points 1

and 2, and I agree that it would make the page much more inviting to

newcomers.

Point 3 would take some time. I had never noticed that before.

Personally, I think the issue about documentation isn’t that it is

boring (I actually find them interesting), it is that by the time one

gets into a project to actually start contributing, you become immune to

the deficiencies in the documentation. Insights like these from

newcomers are like gold to those of us who have been around for a while.

Feel free to either create some pull requests to address some of these

points, or at least file some bug reports so that we don’t completely

forget this. I may even be able to pick up some of it once my book

finalizes for printing in the next week or two.

Cheers!

Ben Root

On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini

<fabio.zanini@…552…1225… mailto:fabio.zanini@...1225...>
wrote:

Dear Thomas,

Finally got some time to reply about the docs. My main point is not

about the API docs themselves, although they would need some tuning à la

MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am

considering an issue with the non-API part of the docs, i.e. the user

guide, tutorial, and website.

MY OLD PROBLEM WITH THE DOCS

Now I am more experienced with mpl so I just read the API docs and

figure my way through, but at the beginning I remember that whenever I

was wondering about something I would quickly end up in either of two

places:

- the pyplot API page: [http://matplotlib.org/api/pyplot_api.html](http://matplotlib.org/api/pyplot_api.html)

This is a giant blob of a page and takes several seconds just to load.

It's lacking any kind of menu or navigation help, just the whole docs

straight out - alphabetical order - and bam!

- stackoverflow

Here people give practical suggestions, but they are inconsistent (some

use pyplot, some axes methods, sometimes even more low-level code). I

mean, it does work, but it's messy and not very instructive for newbies

(imagine learning say chemistry from stackoverflow, not fun uh?)

HOW TO MAKE IT BETTER

This one's harder, but I'd have a couple of ideas:

1. better home page

The beginner's guide should be accessible from the home page in ONE

click, possibly highlighted in a frame or so. It currently takes 3

clicks on small text hyperlinks to get to some introduction, the pyplot

tutorial:

HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL

(and it's not even the first link on those pages). Some quick visual

snippet (possibly interactive e.g. an IPython notebook?) and maybe a

video tutorial like golang would be helpful:

[http://golang.org/](http://golang.org/)

2. More navigation support on the pyplot API page

I realize API docs need to be somewhat stiff in order to make sure you

find what you're looking for (alphabetical order and so), but some

side-menu, quick example, or highlighting of the most common items

(plot, scatter) would be useful. I've read the acorr API docs 100 times

by now, and never, ever used it ;-P

3. clear presentation of the protagonist (Axes)

As far as I understand, the main object for the user is the Axes class.

For instance, does the code below look familiar to anyone?

ax.plot(x, y)

ax.scatter(x, y)

ax.set_xscale('log')

ax.set_xlabel('My x axis')

ax.set_xticks(...)

ax.legend()

ax.set_title('My title')

ax.grid(True)

Nonetheless, this kind of Axes-based coding is not even mentioned in the

beginner's guide. You may now think it's in the advanced guide but, no!

- the advanced guide only talks about "Artists" in general, not the Axes

in particular: "Artist tutorial", "Customizing your objects", etc.

I am not criticizing past mainteners for this organization, but I would

support a more Axes-centric tutorial in the beginner's guide.

As of the time issue, it's the usual problem, nobody wants to do the

docs because they are boring. It's true, it's a bit boring. But that

also depends a bit: writing API docs can be boring, but writing a

tutorial for newbies can be fun!

Cheers,

Fabio

------------------------------------------------------------------------------

Dive into the World of Parallel Programming The Go Parallel Website,

sponsored

by Intel and developed in partnership with Slashdot Media, is your

hub for all

things parallel software development, from weekly thought leadership

blogs to

news, videos, case studies, tutorials and more. Take a look and join the

conversation now. [http://goparallel.sourceforge.net/](http://goparallel.sourceforge.net/)

_______________________________________________

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

<mailto:Matplotlib-devel@lists.sourceforge.net>

[https://lists.sourceforge.net/lists/listinfo/matplotlib-devel](https://lists.sourceforge.net/lists/listinfo/matplotlib-devel)

Dive into the World of Parallel Programming The Go Parallel Website, sponsored

by Intel and developed in partnership with Slashdot Media, is your hub for all

things parallel software development, from weekly thought leadership blogs to

news, videos, case studies, tutorials and more. Take a look and join the

conversation now. http://goparallel.sourceforge.net/

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

6

OK made a pull request with the first changes (1): #4187.

Cheers,
F

···

On 03/03/2015 10:56 PM, Benjamin Root wrote:

The website is generated by sphinx from the docstrings and other
components in the doc/ directory of the matplotlib project. The file for
the home page can be found:
https://github.com/matplotlib/matplotlib/blob/master/doc/_templates/index.html

By the way, the file for the "Documenting mpl" page is here:
https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst

And, like I said, even if you don't get around to actually making any
changes, at the very least, I would file these issues as "bugs" to our
issue tracker.

Cheers!
Ben Root

On Tue, Mar 3, 2015 at 4:40 PM, Fabio Zanini > <fabio.zanini@...1225... <mailto:fabio.zanini@…1225…>> > wrote:

    Hi Ben,

    Well, excellent or not I just hope it helps a bit. I can put some effort
    if people agree that this is useful, though I am quite busy at the
    moment. Who's currently actually managing the website?

    Thx!
    F

    On 03/03/2015 21:33, Benjamin Root wrote:
    > This is excellent insight! It should be fairly trivial to fix points 1
    > and 2, and I agree that it would make the page much more inviting to
    > newcomers.
    >
    > Point 3 would take some time. I had never noticed that before.
    > Personally, I think the issue about documentation isn't that it is
    > boring (I actually find them interesting), it is that by the time one
    > gets into a project to actually start contributing, you become immune to
    > the deficiencies in the documentation. Insights like these from
    > newcomers are like gold to those of us who have been around for a while.
    >
    > Feel free to either create some pull requests to address some of these
    > points, or at least file some bug reports so that we don't completely
    > forget this. I may even be able to pick up some of it once my book
    > finalizes for printing in the next week or two.
    >
    > Cheers!
    > Ben Root
    >
    >
    > On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini
    > <fabio.zanini@...1225...
    <mailto:fabio.zanini@…1225…>
    <mailto:fabio.zanini@…1225…
    <mailto:fabio.zanini@…1225…>>>
    > wrote:
    >
    > Dear Thomas,
    >
    > Finally got some time to reply about the docs. My main point
    is not
    > about the API docs themselves, although they would need some
    tuning à la
    > MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am
    > considering an issue with the non-API part of the docs, i.e.
    the user
    > guide, tutorial, and website.
    >
    > MY OLD PROBLEM WITH THE DOCS
    >
    > Now I am more experienced with mpl so I just read the API docs and
    > figure my way through, but at the beginning I remember that
    whenever I
    > was wondering about something I would quickly end up in either
    of two
    > places:
    >
    > - the pyplot API page: http://matplotlib.org/api/pyplot_api.html
    >
    > This is a giant blob of a page and takes several seconds just
    to load.
    > It's lacking any kind of menu or navigation help, just the
    whole docs
    > straight out - alphabetical order - and bam!
    >
    > - stackoverflow
    >
    > Here people give practical suggestions, but they are
    inconsistent (some
    > use pyplot, some axes methods, sometimes even more low-level
    code). I
    > mean, it does work, but it's messy and not very instructive
    for newbies
    > (imagine learning say chemistry from stackoverflow, not fun uh?)
    >
    >
    > HOW TO MAKE IT BETTER
    >
    > This one's harder, but I'd have a couple of ideas:
    >
    > 1. better home page
    >
    > The beginner's guide should be accessible from the home page
    in ONE
    > click, possibly highlighted in a frame or so. It currently takes 3
    > clicks on small text hyperlinks to get to some introduction,
    the pyplot
    > tutorial:
    >
    > HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL
    >
    > (and it's not even the first link on those pages). Some quick
    visual
    > snippet (possibly interactive e.g. an IPython notebook?) and
    maybe a
    > video tutorial like golang would be helpful:
    >
    > http://golang.org/
    >
    > 2. More navigation support on the pyplot API page
    >
    > I realize API docs need to be somewhat stiff in order to make
    sure you
    > find what you're looking for (alphabetical order and so), but some
    > side-menu, quick example, or highlighting of the most common items
    > (plot, scatter) would be useful. I've read the acorr API docs
    100 times
    > by now, and never, ever used it :stuck_out_tongue_winking_eye:
    >
    > 3. clear presentation of the protagonist (Axes)
    >
    > As far as I understand, the main object for the user is the
    Axes class.
    > For instance, does the code below look familiar to anyone?
    >
    > ax.plot(x, y)
    > ax.scatter(x, y)
    > ax.set_xscale('log')
    > ax.set_xlabel('My x axis')
    > ax.set_xticks(...)
    > ax.legend()
    > ax.set_title('My title')
    > ax.grid(True)
    >
    > Nonetheless, this kind of Axes-based coding is not even
    mentioned in the
    > beginner's guide. You may now think it's in the advanced guide
    but, no!
    > - the advanced guide only talks about "Artists" in general,
    not the Axes
    > in particular: "Artist tutorial", "Customizing your objects", etc.
    > I am not criticizing past mainteners for this organization,
    but I would
    > support a more Axes-centric tutorial in the beginner's guide.
    >
    > As of the time issue, it's the usual problem, nobody wants to
    do the
    > docs because they are boring. It's true, it's a bit boring.
    But that
    > also depends a bit: writing API docs can be boring, but writing a
    > tutorial for newbies can be fun!
    >
    > Cheers,
    > Fabio
    >
    >
    >
     ------------------------------------------------------------------------------
    > Dive into the World of Parallel Programming The Go Parallel
    Website,
    > sponsored
    > by Intel and developed in partnership with Slashdot Media, is your
    > hub for all
    > things parallel software development, from weekly thought
    leadership
    > blogs to
    > news, videos, case studies, tutorials and more. Take a look
    and join the
    > conversation now. http://goparallel.sourceforge.net/
    > _______________________________________________
    > Matplotlib-devel mailing list
    > Matplotlib-devel@lists.sourceforge.net
    <mailto:Matplotlib-devel@lists.sourceforge.net>
    > <mailto:Matplotlib-devel@lists.sourceforge.net
    <mailto:Matplotlib-devel@lists.sourceforge.net>>
    > matplotlib-devel List Signup and Options
    >
    >

    ------------------------------------------------------------------------------
    Dive into the World of Parallel Programming The Go Parallel Website,
    sponsored
    by Intel and developed in partnership with Slashdot Media, is your
    hub for all
    things parallel software development, from weekly thought leadership
    blogs to
    news, videos, case studies, tutorials and more. Take a look and join the
    conversation now. http://goparallel.sourceforge.net/
    _______________________________________________
    Matplotlib-devel mailing list
    Matplotlib-devel@lists.sourceforge.net
    <mailto:Matplotlib-devel@lists.sourceforge.net>
    matplotlib-devel List Signup and Options