PhysicsOfMobility/ridepy

Implement JOSS reviewer comments regarding documentation

fxjung opened this issue · 0 comments

Helpful suggestions by @abhishektiwari:

  • Please consider improving the Github repo Readme by adding installation instructions and contribution guidelines. I know these are already covered by documentation portal in great details but given Github repo is landing page for this software paper I highly recommend to update Readme.
  • Please consider improving the A statement of need and Summary covered by Github repo Readme and documentation portal landing page, and align them with paper. I feel they all read differently and only after reading the software paper or the conceptual overview one can understand the problem statement and target audience.
  • As mentioned by paper ridepy's modular design makes customization easy, while the included modules allow for a quick start, documentation will benefit with examples of how to extend the ridepy modules with a real-world use case. API/code documentation for supported dispatching algorithms partially covers this but additional details will help users.
  • Installation instructions worked but can be little bit clear by calling out pre-installation of C++ build environment and the Boost libraries. For instance, on Debian run sudo apt update && sudo apt -y install build-essential libboost-all-dev before pip install ridepy.