Re: [matplotlib-devel] API Documentation usability

[Fabio Z. <fab...@tu...>]

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
> <fab...@tu... <mailto:fab...@tu...>>
> 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 ;-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/
>     _______________________________________________
>     Matplotlib-devel mailing list
>     Mat...@li...
>     <mailto:Mat...@li...>
>     https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 
>