[ENH] Document new dataset description file

[alyssadai]

• Closes Document use of dataset_description.json #348

Changes proposed in this pull request:

• Add new page "Preparing the dataset description"
• Update example CLI commands to use new --dataset-description arg
• Add mkdocs-madlibs plugin (and required stylesheet) for templated dataset description code snippets

Checklist

Please leave checkboxes empty for PR reviewers

• PR has an interpretable title with a prefix ([ENH], [FIX], [REF], [TST], [CI], [MNT], [INF]) see our Contributing Guidelines for more info)
• PR links to GitHub issue with mention Closes #XXXX
• Checks pass
• If an existing page was renamed or deleted, redirects have been added to the mkdocs.yml config

[netlify]

✅ Deploy Preview for neurobagel-documentation ready!

Name	Link
🔨 Latest commit	357aaf8
🔍 Latest deploy log	https://app.netlify.com/projects/neurobagel-documentation/deploys/696001bec7476900087779d0
😎 Deploy Preview	https://deploy-preview-351--neurobagel-documentation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[surchs]

Thanks @alyssadai for writing the docs! Reads well and clear!

I have some high level suggestions that I think would make this easier to digest for a new user:

1. Put the example of the file at the very top, right after a (brief) explainer. Shows the user what we're dealing with
2. Have the "editable template" second. Gets the user going immediately and avoids having to sift through text that may or may not be relevant.
3. Add a downloadable template file as well - parallel to the template text box. Lets user go direct to their text editor if wanted and avoids additional step of "create new text file first".
4. Turn the BIDS / not-BIDS part into just an admonition. Avoids overlap and cognitive load for user to parse the difference between sections. Main message: "you may have this file already from BIDS, in this case just add the keys you don't have from the template as needed" - this should be easy because a BIDS dataset_description.json is valid for us (reverse not, but that's not a real worry because if they didn't have a dataset_description.json to begin with, then their BIDS dataset was never valid).

[alyssadai]

@surchs, thanks for your suggestions! I implemented them all, but there's one that probably needs another look:

Add a downloadable template file as well - parallel to the template text box. Lets user go direct to their text editor if wanted and avoids additional step of "create new text file first".

So because JSON can be rendered directly in the browser, I don't actually think (or haven't found a way) to force a direct file download for a JSON file using either markdown attributes or HTML tags - for me at least, it always opens in a separate tab as plaintext. The only workaround I could find was to zip the file first, which I've done in the latest commit. Is that fine do you think?

[surchs]

Hey @alyssadai

The only workaround I could find was to zip the file first

Interesting, I hadn't expected this. I'm not sure what to do here. First of all: great solution. But the reason I suggested the file is to make it easier on the user to use our template. Seems to me that unzipping a file is not a lot easier than either saving a JSON file from a browser tab or copy-pasting the template directly.

So I'd say in order of preference for me:

1. Remove the downloadable link completely since it doesn't work as expected and just ask users to copy-paste our template from the docs
2. Leave the download link as is as a JSON and mention to users that they'll have to save the file after it opens in a new tab. Not ideal, some users may get confused and save this as a different file format / mix it up, etc. But maybe still easier
3. Make the file zipped and explain to users how to unzip it. Least preferred, depending on system may require other programs, not simple for non-technical users to do on a Linux machine etc.

[surchs]

Thanks @alyssadai, I think this now reads very clear and straightforward. I also like the position of the "I have a file from BIDS dataset" info box - I was spotting that exactly when I was wondering about that question (i.e. after reading the editable box). Very cool.

🧑‍🍳