JOSS Review - Docs

[Nicholas Pritchard]

Hi @David-McKenna; I'm looking through the docs now.
This relates to the JOSS Review
Great start; I have a few extra things I'd like to see.

• In the README.md, part of a statement of need mentions the intended audience. I assume the package is first and foremost targeted at I-LOFAR, but it's worth mentioning the intended users explicitly.
• More on that, it's worth expanding some of the acronyms in the README (LOFAR, CEP)
• I see you link to particular pages in the docs from the main README, but consider adding a top-level README in the docs/ folder to give an overview of the docs from there
• You should mention docker support and give an example of that too, since the docker file is present

I'm fine with having the docs sit as Raw markdown on GitHub, but consider building them as a standalone asset (e.g., https://www.mkdocs.org/), but this is a nice-to-have rather than a must-have.

Typos (nit-picky, but worth cleaning up):

• README_CLI.md
  • 32 suported
  • 32 usedmultiple
  • 35 outputs
  • 36 represententing
  • 41 option -> options
  • 41 prperties
• COMPILERS.md
  • 10 theads
  • 14 sigificant
  • 16 accellerate

Otherwise, I appreciate seeing the CLI args documented and the example you've written, the investigation into compiler choice is also neat.
Feel free to discuss anything with me further 😄

[David McKenna]

Hey Nicholas (@pritchardn),

Thanks for taking on the review for the submission! It seems like I agree with you on everything. Going through your points,

In the README.md, part of a statement of need mentions the intended audience. I assume the package is first and foremost targeted at I-LOFAR, but it's worth mentioning the intended users explicitly.

Aha. From the JOSS checklist, I assumed this was just needed in the paper. I'll update that section.

More on that, it's worth expanding some of the acronyms in the README (LOFAR, CEP)

Will do.

I see you link to particular pages in the docs from the main README, but consider adding a top-level README in the docs/ folder to give an overview of the docs from there

Will do.

You should mention docker support and give an example of that too, since the docker file is present

Hmm, I thought I had that, I guess I lost it somewhere while getting the 0.9 release together. I'll add a note to the README and an extra document to the docs folder.

I'm fine with having the docs sit as Raw markdown on GitHub, but consider building them as a standalone asset (e.g., https://www.mkdocs.org/), but this is a nice-to-have rather than a must-have.

MkDocs certainly sounds useful, I'll look into it. I should be able to host it on one of my domains fairly easily.

And of course, I'll patch up those types.

I'll try to get all of these changes together later this week, I'll ping you when I merge in a PR with the changes.

Cheers,
David