JOSS review item: Documentation

[Matthew-Jennings]

I agree with @theanega's comments regarding documentation. I suggest:

1. Adding your Statement of Need to the welcome page.
2. Adding near the top of the README some prose (outside of the examples section) that explains all primary functionality at a high level. I notice in your Issues that you plan to support some so far unsupported modalities (planar X-rays and SPECT). If some non-negligible fraction of users desire this functionality and you're aware that it's not supported, you should state this outright as a limitation of the library. Generally, known inclusions and limitations of interest to a non-negligible fraction of users should be stated, IMHO. Another example that comes to mind is python version compatibility.
3. Adding tutorials and how-to guides with deeper dives into demo applications that showcase features you've implemented and explain use of MIRPs tools in detail. Include demonstration of things like why a user might select one input option over another, or which tool/function is more useful for a given task than another, etc. This might seem a little nitpicky, but a key theme in your Statement of Need is standardisation. A lofty goal, to be sure, but one that cannot be achieved at any scale without substantial user-friendliness. Code can be tricky to grok, a technical reference helps only a little, and users are lazy...
4. Seriously considering how much you'd like others to contribute to the project and minimise its "bus factor". Perhaps you don't care (at least at this stage) and that's completely fine. But if you do, you'll need to flesh out your contributors guide quite a bit more, and advertise a little enthusiastically than "if you've got an idea, open an issue". A tool is unlikely to become a standard without some redundancy in project maintenance.

If you want to get into the weeds of documentation, Diátaxis is an excellent resource. In their parlance, you already have a Reference, my suggestion in #72 is to flesh out How-to guides and my suggestion in point 3 is either a Tutorial or an Explanation or some hybrid of the two. Points 3 (taken to its full extent) and 4 need not hold back publication in JOSS, but It would be nice to see one nicely fleshed out tutorial/explanation page for one of your core functions.

[drcandacemakedamoore]

I think the point here about bus factor is very critical for the software itself in the future. Another dimension to the issue is getting people to review all your PRs. This, in my experience, can dramatically improve your software. In the case of this software I think the community of researchers, myself included will be very excited. It is not a JOSS requirement, but I encourage you to reach out to the community. There are those among us who will be willing to help keep the software alive and maintained. Unfortunately, the destiny of a lot of software libraries is to die when someone finishes a PhD, but it doesn't have to be this way. Feel free to reach out to me if you want more ideas on software sustainability.

[alexzwanenburg]

In version 2.2.1 I was able to address some of the suggestions. Some things still need to be addressed:

• [x] Add statement of need (or at least make it clearer).
• [x] Add additional tutorials, e.g. on using filters.
• [x] Document design concepts for contributors:
  • [x] Importing images and files.
  • [x] Internal image and mask formats.
  • [x] Defining workflows.
  • [x] Feature classes.
  • [x] Filter classes.
  • [x] Designing tests.

@drcandacemakedamoore I hope we will be able to grow the community around MIRP 😃

[alexzwanenburg]

Reopened for JOSS review.

[alexzwanenburg]

I added a statement of need here: https://oncoray.github.io/mirp/introduction.html#why-mirp

There are now two tutorials:

• https://oncoray.github.io/mirp/tutorial_compute_radiomics_features_mr.html
• https://oncoray.github.io/mirp/tutorial_apply_image_filter.html

The contributing section was extended:

• I updated https://oncoray.github.io/mirp/contributing.html
• I wrote https://oncoray.github.io/mirp/design.html to discuss the overall design of MIRP.
• There is now a document on tests: https://oncoray.github.io/mirp/contributing_tests.html

[Matthew-Jennings]

Thanks, @alexzwanenburg!

1. Statement of need looks good :) - close.

2. What are your thoughts on this point? I do think that it's not immediately obvious to a prospective user (reading the README, or even the docs intro) what high-level functionality MIRP contains. Example/tutorials are great, but a user will assume this only shows a curated subset of functionality. You do state that it's an IBSI compliant medical image analysis toolkit, but this feels too broad. Probably the closest docs content to what I'm talking about is buried in your Contributing section under submodules

3. I like your tutes! Add more when you have the time/think it's suitable, but two are enough for the purposes of JOSS publication - close.

4. Nice to see the contrib section. Pretty well fleshed out. - close (but still consider bus factor and @drcandacemakedamoore's comments)

5. NEW: It took me (embarrassingly?) a little while to see that your technical reference (API documentation) was located in your DEEP DIVE section. This is probably fine, but maybe you could add "API Documentation" in parentheses next to the "DEEP DIVE" seciton title, or something. Not important for JOSS - just a thought.

[alexzwanenburg]

Thanks for the feedback!

What are your thoughts on this point? I do think that it's not immediately obvious to a prospective user (reading the README, or even the docs intro) what high-level functionality MIRP contains. Example/tutorials are great, but a user will assume this only shows a curated subset of functionality. You do state that it's an IBSI compliant medical image analysis toolkit, but this feels too broad. Probably the closest docs content to what I'm talking about is buried in your Contributing section under submodules

I have updated the README to provide a very short overview of what MIRP does, and to show the tutorials more clearly.

NEW: It took me (embarrassingly?) a little while to see that your technical reference (API documentation) was located in your DEEP DIVE section. This is probably fine, but maybe you could add "API Documentation" in parentheses next to the "DEEP DIVE" seciton title, or something. Not important for JOSS - just a thought.

I renamed the section to Documentation and API.

[alexzwanenburg]

Is it okay if I close this issue?

[Matthew-Jennings]

Yes, no worries