Re: [matplotlib-devel] API Documentation usability

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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