[JOSS Review] Documentation page
FlorianK13 opened this issue · 5 comments
There is a documentation page at https://canimus.github.io/cuallee/ hosting all the files in the docs folder.
However it seems to be not quite finished. Is it part of the official documentation? Or is the Readme.md the official documentation?
This issue is part of a JOSS Review
Hi @FlorianK13 thanks for the review process. We started with the idea of building an external site, through Github Pages to host the documentation. However, we decided that investing time in more testing could render better results. As you highlighted, the README.md contains a comprehensive view of all checks available today, and the unit tests, are our best demonstration of the functionality. Nevertheless and without excuses, we should put the references we have in the docs up to date, so that it represent the state of the project, and indeed, can help guide the community.
Hi @canimus, I have to say that I really struggle with the documentation in the Readme.
First a more general remark: Your software seems to have lots of features, i.e. lots of test cases in combination with several different data frameworks. This is (of course) a great thing. Putting the documentation of such an extended software just in one Readme file seems complicated. At least you would need a very clear structure and some sort of navigation like a table of content at the beginning for easier navigation.
Regarding the documentation in the Readme: You start by defining supported frameworks and the installation. Then you use one sentence to introduce Checks. I assume that checks are the central entrypoint and that all tests follow this schema
check.test1("column").test2("column").validate(df).show() - but this is not documented, so maybe I'm wrong?
After that, some tests are mentioned and some example code is given. When comparing these descriptions with the Catalogue it seems like not all tests are described. Just as an example, has_entropy takes three arguments column, value, and tolerance. When using this test, I would need to guess what they represent. A solution could also be docstring documentation here. And mkdocstrings could turn your code documentation in a documentation page - but this is just how I would go here, if you feel more comfortable with other solutions that is also fine.
You can also check the review criteria for documentation pages at the JOSS website
Hi @FlorianK13 , we opted to put more effort in bringing the docs site alive, with accurate references:
https://canimus.github.io/cuallee/
That hopefully will help to meet the criteria, and provide the structure you very well are suggesting to adhere to, so that navigating the package functionality does not represent a challenge for the end user.
Thanks for your time and patience, on the resolution, hopefully by next week, we will have a docs version up to date, with all the Checks up to date. Warm regards, Herminio
Ah great, then we had a misunderstanding.