[JOSS]: walk through documentation to catch deficiencies

[yarikoptic]

• download .tgz under http://datasets.datalad.org/?dir=/dbic/QA/sourcedata/sub-qa/ses-20230626
• read the docs: https://heudiconv.readthedocs.io/ and see if you could get to use heudiconv to get basic conversion going/done

[asmacdo]

Using only the information provided by the docs, I don't think a newbie had sufficient information to use heudiconv. The docs make up for what they lack with external links, specifically the tutorials. A sufficiently motivated user will be able to use use heudiconv, but we can significantly ease the barrier to entry.

from the JOSS paper, the Statement of Need is helpful for understanding the context, and that info could go into a "why heudiconv" or similar section in the docs.

Heudiconv 101 section is very short, and is the only section that explains what to do. Unfortunately this noob was too lost to get much out of it prior to reading other sources.

Specific improvements

• what is meant by heuristic in this context is not clear without proceeding to the inner pages. The summary should be understandable on its own. A definition specific to this context, ie, "a file that defines the relationship between DICOM data and the desired structured output" would be helpful.
• lack of tutorials or examples. The tutorial from @jdkent is very clear and concise-- imo it would convert well into an official tutorial. or the Stanford tutorial
  • Each provided heuristic should at least have a blurb in the docs (like the JOSS paper) and possibly an explanation of when it is useful.
  • What makes the the reproin example so good? Could we use the reproin heuristic outside the context of reproinfor a tutorial?

Does a researcher know the format that they need to get to, and the metadata that needs to be brought along? For me, a non-neuroscientist, a user's end goal is not super clear other than for instance following the BIDS spec. It makes sense this might be inherent to the specific situation, so not documentable. However it might be cool if we made up a user scenario for the tutoroal. That way, the tutorial doesn't just show "what", it shows "why", helping the user learn to make decisions that are based on typical goals.

To what degree can we copy from the JOSS paper? a lot of that could go into the docs nearly exactly if that's ethical and legal or whatever.

[asmacdo]

I think we are good now