[JOSS Review] Feedback and questions
rafmudaf opened this issue · comments
Catch-all issue for feedback and questions related to JOSS Review
The JOSS review is at openjournals/joss-reviews#6758.
Functionality
- Functionality: Have the functional claims of the software been confirmed?
- I did not verify the API download method
Documentation
- A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
- I think you've done a good job in the docs, but the JOSS paper is really good in this area. A suggestion is to take some of the "Statement of Need" section and incorporate it into the docs landing page.
- Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
- Not an issue, just a suggestion: The installation instructions are on the README but I don't see it anywhere in the docs site. Maybe I missed it. However, it would be helpful to have it again in the "Getting Started" section. This is often where the installation instructions are included, so it was my first guess as where to look.
Separately, other suggestions
- In CONTRIBUTING.MD, there's a reference to "USERS.cff", but I don't see this file in the repository.
- This list and a few others aren't rendered how you probably wanted in the docs.
Ideas of solution
Overall, I think this project is in a good state. As part of the JOSS review, I had the unique opportunity to read through your project for the first time, and I simply wanted to capture my first impressions here in case it's helpful. The feedback above are only suggestions.
Workflow checklist
- I am aware of the workflow in CONTRIBUTING.md
Also, I think your docs site looks really nice. It has the right amount of information, highly readable 👌
@FlorianK13 I had initially noted in the issue that I was not finished with the review. I've now completed it, so I will not edit this issue anymore.
Thanks @rafmudaf for this issue, I'll work through your points within this week.
The changes were merged in #527