Recommended approach to store tutorial materials

Support
1

Today I discovered that a PDF linked from a documentation wiki page disappeared (wiki page: https://www.slicer.org/wiki/Documentation/Nightly/Modules/MultiVolumeExplorer, broken link: https://www.slicer.org/slicerWiki/images/8/8d/MultiVolumeExplorer_Meysam_SNR-April2013-v4.pdf).

Are there any recommendations how attachments for various Slicer-related resources should be stored? How is this done with the on-going migration to ReadTheDocs?

I think it would be nice to agree on some recommendation for storing attachments going forward. I am reluctant to use Slicer wiki for this purpose.

2

One idea to handle this - we could upload those to GitHub, and link from wiki pages corresponding to individual repositories. This way links would be maintained by GitHub. It is easy to upload files and associate them with GitHub repositories using the workaround below. I am thinking to use this approach going forward.

3

You can only upload certain files as issue attachments and it is hard to keep track of the files. However, we have several options:

  • A. Upload files as release assets (as we do it for Slicer test data): unlimited file storage, you can drag-and-drop files to upload, can be used as CMake ExternalData server (need to use hash as file name), but no versioning, downloading many files at once is tedious, uploading requires repository write access
  • B. Upload files as source files in git repository (as we do it for PerkLab bootcamp training materials): easy to upload files (click a button then drag-and-drop file), version-controlled, users without write access can request adding of new files, easy to download all files, but repository size can grow big if large frequently changing binary files are stored, maximum file size is 100MB (warning at 50MB), repository maximum size is 100GB (recommended 1GB, warning at 75GB).
  • C. Keep them in a shared OneDrive folder (as we do it for SlicerIGT tutorials): slides can be viewed/edited online, without downloading, no limit on file size, version history can be maintained, easy to upload/download in bulk, can sync with local folder, but write access to the folder cannot be shared easily (trusted people may get write access but the user community cannot propose changes easily; github account cannot be used for authentication), links
    are not guaranteed to be permanent, only for MS Office file formats
  • D. Similar to C but with Google Drive and Googe Docs instead of OneDrive and MS Office (I don’t know any actual usage of this model in Slicer’s ecosystem).
  • E. Create tutorials from scratch using markdown/javascript-based tools: all open-source and vendor-independent, but only suitable for simple text + non-annotated image content due to lack of sophisticated authoring tools (some tools appear then usually die off within a few years)

For me it seems that the two most viable options are B (to promote wider contributions and independence from MS Office) and C (for maximum convenience of a small number of contributors), but I would be interested in hearing about other options.

1 Like
4

As an example of option D, we did some tutorials with sample data for Perk Tutor (http://perktutor.github.io/Help.html)…

1 Like
5

Indeed, but the list includes ZIP. Citing https://help.github.com/en/github/managing-your-work-on-github/file-attachments-on-issues-and-pull-requests:

image

I guess I am ok with B, as long as the repository for data is not the same as the code repository. C and D are less attractive, because those spaces may belong to the institutions, storage is limited and user may hit the quota, and it is impossible to control availability in the general case. I like the approach I demonstrated, because it is so quick and easy, the threshold is very low for non-developers, and often we deal with files that are not expected to be updated.

We used to have Midas, but it is gone, and I don’t know about Girder space for Slicer.

Should we set up a dedicated repository under the Slicer organization to keep this kind of content (PDFs and various tutorial materials)? Would sample images go to that repo too?

6

@freephile may be able to comment more. He told me that some similar path issues are being addressed during the wiki transition.

7

A few comments about the slicer wiki…

The deprecated ‘slicerWiki’ url mentioned at the outset of this post is now working again in the newly migrated wiki system (using rewrite rules).

The newly upgraded wiki is able to store file assets of virtually any type. We currently allow png, gif, jpg, jpeg, webp, csv, doc, docx, ico, ics, jar, json, kml, mm, mov, mp3, mpg, odc, odg, odp, odt, owl, pdf, ppt, pptx, psd, qt, svg, txt, vsd, wmv, xls, xlsx, xml, zip, flac, mkv, mp4, oga, ogg, ogv, wav, webm.

PDF files are handled by a special viewer; and they are indexed for search inclusion.

The wiki allows admins to ‘side load’ (from another URL) files up to 500MB in size; and upload 8MB files from your desktop. (8MB may be increased to suit your needs).

With the new editors (Visual Editor and Source Editor), you can drag and drop files to be uploaded as you edit pages… You don’t need to perform a separate step.

2 Likes