EcoJulia / Diversity.jl

Julia package for diversity measurement
http://docs.ecojulia.org/Diversity.jl/
BSD 2-Clause "Simplified" License
34 stars 9 forks source link

Improving documentation #43

Open PeetoomHeida opened 2 years ago

PeetoomHeida commented 2 years ago

I am trying to read through the documentation to understand how to use this package. I am impressed with the overall coverage of possible analyses that someone might want to run, however I think that the package is designed in a fairly opinionated manner/with a specific paradigm in mind, this is not a problem per se, but without more explicit documentation to hold the hands of new users, I think it is a very steep learning curve. I am coming from R's vegan, and am having a hard time figuring out what some of the options available are for, or how they relate to real world datasets. I am happy to help try to flesh out some of the documentation. I think the first part would be to give better examples of different Metacommunity constructions and to show how partitions can affect the output from various diversity functions. Additionally, I think adding a more explicit description of how to conceptualize "order" in the package and in general would go a long way towards improving the user experience for new users or those coming from vegan.

richardreeve commented 2 years ago

Hi @PeetoomHeida - thanks very much for your feedback. I agree it is regrettably a steep learning curve, but we're also happy to add in other diversity measures (which I see you have, thanks!) since there aren't other diversity packages in Julia. The best introduction to the paradigm is definitely the arXiv paper, and the docs for the R package rdiversity. Maybe we can have a chat about what the best approach would be for fleshing out the docs - it hasn't been a big priority for us as we just use it for our own work... that's not a great thing I know!