Breakout tutorial - Githubissues

open-ephys / bonsai-onix1-docs

Documentation for the OpenEphys.Onix1 Bonsai package

https://open-ephys.github.io/bonsai-onix1-docs/

Creative Commons Attribution Share Alike 4.0 International

0 stars 2 forks source link

Breakout tutorial #39

Closed jonnew closed 3 months ago

jonnew commented 3 months ago

This a first draft of the breakout board tutorial. It's still missing a data loading script and explanation of said script but its a base to start commenting on and improving.

jonnew commented 3 months ago

Thanks for the feedback:

SVG - yeah for sure. Also a non numerical file naming scheme because numerical ordering makes it weird to put pictures in between existing ones
Wall of text - yes. I'm hoping that the section is further expanded with mor explanatory images. I would like you to look into that when you have time.

So, I will go through these edits and implement. Also I want to make a data loading script, which I will put at the bottom. After that, it would be good if you could flesh out with even more images.

cjsha commented 3 months ago

Quick aside. If you select a bunch of operators and click Ctrl+Shift+E (the export hotkeys), you can export a snippet of a workflow. I try to demonstrate in the below screenshot where I'm drag-selecting a section of operators you want to export and then export (you don't have to be drag-selecting while pressing Ctrl+Shift+E - as long as the operators are selected).

Maybe this becomes annoying to maintain if you change the properties in the overarching workflow.svg though

jonnew commented 3 months ago

uhhh... oh. Thats helpful.

cjsha commented 3 months ago

One more thing, what convention should we follow for capitalizing headers?

jonnew commented 3 months ago

Good question. I think we should follow the Open Ephys GUI docs convention:

Site Section Titles
Page Titles
Page section titles

cjsha commented 3 months ago

I'm starting to wonder if we should break this tutorial down into smaller sections. I think the "wall of text" feeling isn't due to a lack of images, I think it's more due to the sheer amount of content/text. For instance, each of these could be its own page:

If we do want to break up the text a little bit, the only images I can think of adding are ones that indicate to the user how the breakout board is supposed to behave if it's functioning correctly. Here are some examples:

Screenshots showing visualizers (in a section like "Memory monitor"?)
GIFs that demonstrate the workflow/Onix system responding to or enacting visual changes in "the real world". For instance, if a workflow does something in response to a user setting a digital input HIGH, the user's action + the workflow's response can be shown in a GIF. Or similarly, if Bonsai is controlling the state of an LED, that can be shown in a GIF.

jonnew commented 3 months ago

Although i get what you are saying, I also kinda really don't like it when pages are all cut up into tiny 1 paragraph pieces either. I do think showing visualizer outputs would be a good idea. I think we should throw that into an issue (e.g. Add visualizer in action examples to tutorials) and try to merge this in the meantime.