search

psychoinformatics-de / inm-icf-utilities

MIT License
0 stars 5 forks source link

Main elements of user-facing docs #14

Closed mslw closed 1 year ago

mslw commented 1 year ago

This PR introduces some user guide content, divided in two sections, DataLad- and Browser-based access.

Feel free to add to this PR, or on top of this PR.

mslw commented 1 year ago

I guess that's it from me for today - this largely has a feeling of "this article is a stub" from Wikipedia, but I think there's already some meaningful information and a reasonable structure to build upon.

This is only the "User guide" section, "ICF Personnel guide" and "Developer guide" sections are still empty.

jsheunis commented 1 year ago

I like this current content, well done.

I was thinking about adding more content about the catalog, but I'm not sure that much more than the current

(optional) a catalog directory containing a catalog of the study visits (which can be used to view e.g. available modalities and DICOM series for each visit)

is actually needed. This gives a good summary and once people click on the catalog the rest is pretty self-explanatory.

Have you thought about what the content of the developer and ICF personnel sections would be? I was thinking the former could contain:

mslw commented 1 year ago

Have you thought about what the content of the developer and ICF personnel sections would be? I was thinking the former could contain:

  • an overview of the complete workflow
  • an explanations of how to generate metadata from tarballs and how to reproducibly build the catalog and datalad datasets by using the available scripts.
  • perhaps also a rundown of the CI setup

In my mind that would totally be the scope of developer docs. How deep we want to go and whether this is the place is really up to us.

And the ICF personnel - probably just a rundown of the scripts, what they do, what are the inputs, and a hint that they are meant to be used in automation.

Probably in separate PRs though?

mslw commented 1 year ago

Treating Stephan's comment as a positive review, I think we can merge this for starters, so that the readthedocs page is less empty, and improve later.