Documentation overview

[alexpron]

This issue aims at providing an overview of the available documentation(s) related to Shanoir (and its ecosytem) and their content.

• List currently available sources of documentation
• List topics covered and public (e.g. developpers, maintainers, users)
• List criteria to set content on a given source
• List current architecture and features of each source (e.g. tests)

[alexpron]

List of available sources of documentation:

1. Shanoir main Github repository (https://github.com/fli-iam/shanoir-ng)
2. Shanoir website (https://project.inria.fr/shanoir/)
3. Shanoir Github Wiki (https://github.com/fli-iam/shanoir-ng/wiki)
4. Shanoir REST API (see github README API section)
5. Shanoir beginner tutorial in french (google doc)
6. Shanoir-deploy Github repository README
7. pynoir Github repository README
8. shanoir-downloader Github repository README
9. Shanoir Youtube Channel (http://www.youtube.com/@shanoir-sharingneuroimagin1969)

[!NOTE] Introduction of the wiki explicitly mention that the github wiki is THE main source /entry point of documentation regarding Shanoir and that wiki contains link towards the other sources when accurate.

[!NOTE] Shanoir instances list sources of documentation (i.e. github wiki, github, beginer tutorial and rest api) in a resources tab

flowchart TD

   shanoir-ng[Shanoir Github README]
   restapi[Shanoir REST API Documentation]
   website[Shanoir Static Website]
   wiki[Shanoir Github WIKI]
   useramanual[Shanoir User Manual]
   shanoir-deploy[Shanoir-deploy Github README]
   pynoir[pynoir Github README]
   shanoir-downloader[shanoir-downloader Github README]
   youtube[Youtube Chanel]

   wiki --> shanoir-ng 
   wiki --> website 
   website --> useramanual
   shanoir-ng --> restapi
   wiki --> restapi
   wiki --> useramanual 
   wiki --> shanoir-downloader

[alexpron]

1. Shanoir Github Repository

1.1. /docs

Topics	Status	Public	Documents formats
Anonymization Shanoir Architecture Microservices Shanoir Imports Shanoir Uploader	Deprecated (last modification except a Shanoir Uploader GUI picture is 2020)	Users Developpers	.docx, .xlsx, .json, .png

1.2 README

Topics	Status	Public	Documents formats
Shanoir Architecture REST-API Installation (Configure, Build, Deploy)	Conflicts with wiki on installation instructions ?	Developpers Maintainers	.md

[!WARNING] README states that Github repository is targeting Shanoir developpers and redirect users to the Shanoir project website There is no mention of the Github wiki that is the main documentation entry point

[alexpron]

2. Shanoir Website

Shanoir project website served by Wordpress with independant content (website not built from github repository)	Topics	Status	Public	Documents formats
General Presentation Shanoir Consortium Dev Roadmap News about features Technical keywords	Up to date	People Interested in Shanoir	Wordpress website

[!WARNING] The Shanoir project website does not contain any user information strictly speaking

[alexpron]

3. Shanoir Github Wiki

Shanoir Github Wiki (https://github.com/fli-iam/shanoir-ng/wiki) is described as the main and most up to date source of documentation available about Shanoir. The Shanoir wiki is structured as follows:

• Users documentation
• Operations documentation
• Developers documentation

3.1 Users documentation

• User tutorial (i.e. Shanoir beginner tutorial in french (google doc))
• User features (e.g. User rights) that contains:
  • functional specifications of the feature (e.g. solr search)
  • description of the feature (e.g. How to download data)
  • user tutorials (e.g. Shanoir Study tags

[!NOTE] Each feature does not contain the 3 kind of content (specs, description and tutorial). Most of them contains specs but no user tutorial strictly speaking

[!Important] With the exception of the google doc and the entry on subject tags, there does not seems to be a wiki entry corresponding explicitly to user documentation.

3.2 Operations documentation

• Deployement documentation point toward README (and Deploy ?)

• Deployement dev point toward other instructions

  • which one should be followed ?

  • for which purpose ?

  • script that gather these instructions (pertinent or not) ?

  • Maintenance

    • Storage configuration (docker volumes for data storage and how to adapt to production instance)
    • Daily Operations (daily operations performed on Shanoir instances)

  3.3 Developpers documentation

  • Roadmap (Project Management ?) Similar with information on the website

    • How to contribute to the roadmap ?
    • Roadmap
    • Updates

  • REST API

    • REST API (general considerations about rest API)
    • Swagger doc
    • Markdown documentation of datasets API

  • Development environment

[alexpron]

4. Shanoir REST API

Links to the REST API of Shanoir provided by Swagger (framework to handle API their design and documentation). The endpoints and methods can be tested interactively.

[!NOTE] The REST API links are referencesd into the Github Shanoir Wiki as well as in the Github Shanoir repository > README (duplicates)

[alexpron]

5. Shanoir User tutorial.

User tutorial in French on how to :

• Import DICOM files using Shanoir Graphical Web Interface
• Handle Imported Datasets
  • Visualize
  • Search
  • Download Latest version is from 2020

[alexpron]

6. Shanoir-deploy Github repository

Documentation about Github workflows that deploy shanoir-qualif instances.

TODO: clarify how this interacts with deploy instructions and what should be done to deploy on qualif

[alexpron]

7. [PyNoir] (https://github.com/fli-iam/py_noir/) Github repository

Python client to deal with Shanoir REST API (e.g. connection, get, put)

[alexpron]

8. Shanoir-downloader

Python package that implements all several methods of a python client and focus on downloading data in a secured manner. Hereunder are few functionnalities that are documented in the README of this repository

• download from a set of dataset identifiers
• download from a .csv file
• download from configuration file and conversion into BIDS formatted datalad datasets