Giters

GiovineItalia / Gadfly.jl

Crafty statistical graphics for Julia.

Home Page:http://gadflyjl.org/stable/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Documentation needs improvement. Older releases good habits have been left.

benibilme opened this issue · comments

commented

Hello,

I am trying to learn Gadfly. I am newbei in this area, I am interested in Gadfly because of easier syntax and pure julia implementation.

However I find the documentation is very lacking. As a matter fact, I have encountered documentation of older versions and they seemed better in several aspects than the newer documentation. The latest documentation almost dropped textual descriptions and just give examples. There are many cases where neither textual descriptions or examples are available. I often have to resort to source code but source code is above my level of understanding of Julia.

This is an older version of the documentation
http://gadflyjl.org/v0.5.0/lib/geoms/geom_hline.html

This is new version of the documentation.
http://gadflyjl.org/stable/lib/geometries/#Gadfly.Geom.hline

Apparently, newer version is barely giving information as opposed the previous one which provides one page long description and examples. Somebody got lazy imho.

This is beautiful library and I really wish it is updated with thorough documentation and more examples, and 3d graphics will be added.

If I had enough understanding of the package, I would be very glad to improve the documentation but I am not at that level.

Thank you.

commented

The link you provided above is for the "Library" part of the documentation, there is also a gallery:
http://gadflyjl.org/stable/gallery/geometries/ (that's a link to the Geometries page of the Gallery)

Both the "Gallery" and "Library" have pages for Geometries, Guides, Statistics, Coordinates, Scales, and Shapes, which are on the left tab: http://gadflyjl.org/stable/

commented

I have seen the gallery. However, if you check the links, that I provided you can concur that the library parts of the documentation have been obviously clipped.

For the comparison, please check the documentation of Makie for bar graph. This is api documentation not tutorial or general description pages. This is really very good way of documenting every related feature of bar graph. It has similar pages for every type of graph.

Api documentation provides, a textual description, definition of all attributes with default values and lots of examples which shows usage off almost all attributes and different usages.

https://makie.juliaplots.org/v0.15.1/examples/plotting_functions/barplot/index.html

If I try to dig this information from Gadfly documentation, maybe because of the grammar of graphics thing, the documentation is scattered multiple pages. It is obvious that general usage pages and gallery examples have been assumed to be enough to make the point. However it is not in my opinion.

Even if the library structure forces such a documentation, as a newbie, I really wish to see all relavant information and the detailed api in single place or with links provided, and with lots of examples.

  1. http://gadflyjl.org/stable/gallery/geometries/#[Geom.bar](@ref)
  2. http://gadflyjl.org/stable/lib/geometries/#Gadfly.Geom.bar
  3. http://gadflyjl.org/stable/lib/statistics/#Gadfly.Stat.bar

I am insisting on this issue since I really would like to learn this library intimately and use it daily. I believe, if documented well enough, this library will be main stream library for new julia users for daily routines.