[JOSS Review] Feedback and questions

rafmudaf commented 3 months ago

Catch-all issue for feedback and questions related to JOSS Review

The JOSS review is at https://github.com/openjournals/joss-reviews/issues/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

[x] I am aware of the workflow in CONTRIBUTING.md

rafmudaf commented 3 months ago

Also, I think your docs site looks really nice. It has the right amount of information, highly readable 👌

rafmudaf commented 3 months ago

@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.

FlorianK13 commented 3 months ago

Thanks @rafmudaf for this issue, I'll work through your points within this week.

FlorianK13 commented 3 months ago

@rafmudaf I have added the changes. They will be merged to develop after the review of @chrwm in #527

FlorianK13 commented 2 months ago

The changes were merged in #527

OpenEnergyPlatform / open-MaStR