User experience feedback (Mathieu)

[mathieuboudreau]

I'm not done testing the whole process, as it's taking quite a lot of time updating the T1 book to work with the latest version of Jupyter Book (thanks @zelenkastiot!), but I wanted to leave some early feedback. I'll be updated the list by editing this comment.

General UX

• Before Step 1 (or at the very beginning of it), there's missing some kind of high level explanation of what we expect the users will need to do. The 🗂 Preprint repository structure section is the first time that there's something like this explained through the directory structure, and it might confuse some users no knowing how all these folders will be generated or if they all need to be manually created.

By high level, I mean something like:

As a new user, you will need to:

* Create a Jupyter Notebook of your analyses that you want to share.
* Initialize a Jupyter Book template directory (will generate all the files in the *content* folder) and add your Jupyter notebook(s).
* Create files that reproduce your computing environment (files under the *binder* folder)
* Write all relevant bibliography details (paper.md and paper.bib files)

Not necessarily exactly above, but some kind of high-level instructions that will give the new user a birds eye view of the steps they'll need to take would be helpful to understand all the later instructions.

Broken links

• Below second figure, If you would like to submit a NeuroLibre preprint, please read our submission guidelines.
• Markdown link not rendering correctly:

• In Step 1: We suggest testing repo2data locally before you request a RoboNeuro preview service. Instructions are available here.

Text possibly needing to be updated

• Warning: NeuroLibre is at an alpha stage of development, and is not currently open for submissions.
  • Are we still at alpha stage?
• It is tailored for publishing interactive neuroscience notebooks
  • This reads as if we're limiting submissions to neuroscience notebooks, which I don't think is the case. Maybe it could be reworded, listing neuroscience as an example?
• There's an extra paragraph/space after Contributions are welcome, NeuroLibre is fully open-source that I think could be removed.

[mathieuboudreau]

Kiril was able to update the T1 book to use version 0.10.x of Jupyter Book (repo, site).

I forked and converted the repo in a branch to match the format in the docs, and tried a preview submission (https://roboneuro.herokuapp.com).

I am still encountering this error, with no accompanying messages.

Any clue @agahkarakuzu ?

[ltetrel]

Kiril was able to update the T1 book to use version 0.10.x of Jupyter Book (repo, site).

I forked and converted the repo in a branch to match the format in the docs, and tried a preview submission (https://roboneuro.herokuapp.com).

I am still encountering this error, with no accompanying messages.

Any clue @agahkarakuzu ?

Can you create a new issue for this, so we can continue the discussion there ?

[agahkarakuzu]

I will need to look into this in debug mode to see why it failed.

[ltetrel]

@mathieuboudreau
I think I incorporated most of your concerns in the new version of the doc.
Still let me know about other issues you encounter :)