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 ;-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
smime.p7s
Description: S/MIME Cryptographic Signature
------------------------------------------------------------------------------ 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
