search

oncoray / mirp

Medical Image Radiomics Processor
https://oncoray.github.io/mirp/
European Union Public License 1.2
53 stars 14 forks source link

JOSS review item: Documentation #73

Closed Matthew-Jennings closed 4 months ago

Matthew-Jennings commented 7 months ago

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 commented 7 months ago

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 commented 6 months ago

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

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

alexzwanenburg commented 6 months ago

Reopened for JOSS review.

alexzwanenburg commented 6 months ago

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

There are now two tutorials:

The contributing section was extended:

Matthew-Jennings commented 5 months ago

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 commented 5 months ago

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 commented 4 months ago

Is it okay if I close this issue?

Matthew-Jennings commented 4 months ago

Yes, no worries