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

Move tutorials that are specific to a piece of hardware under the "User Guide" tab #40

Closed cjsha closed 3 weeks ago

cjsha commented 1 month ago

I propose what we're putting in the tutorials currently should go under a dropdown in the User Guide TOC. For example, the WIP Breakout Board tutorial can go a dropdown as drawn in the screenshot below: tutorials-toc Each of those hubs would be its own dropdown.

It's more intuitive to me to put all the hub content together.

I propose tutorials in the tutorial section are more generic instead of hardware-specific. They can be about teaching people about the CreateContext --- Configure<Whatever> --- StartAcquisition motif and how to incorporate this Bonsai package in ways that extend beyond "just using the hardware". For example:

With that said, the tutorial section as I am suggesting it can also go under the User Guide TOC under its own dropdown

jonnew commented 1 month ago

We talked through this and everyone seems to agree this is a good change to make. User Guide pages will focus on what amount to MultideviceFactorys and their use. Tutorials will focus on using the system in the lab for specific purposes.

A good starting point is the breakout tutorial since it, as of writing this, has most of the content required to make the change.

We should also probably break the tutorial into multiple pages.

cjsha commented 1 month ago

If we break the tutorial into multiple pages, with each page corresponding to one or two "Data I/O Operators", I think that makes the "Devices" drop-down under the User Guide section of the docs redundant/obsolete? I think in the way Brandon and I originally envisioned it, a page under the "devices" section was meant to have information that would otherwise be repeated for every hub that contains that device. But all that info should just go into a page under the corresponding hub, and we're ok with repeating that info for each hub.

I do think that info should be templated though, so there is a single source of truth. For instance, almost every hub is going to stream BNO055 data, and it would be better if we're not constantly copying-and-pasting that BNO055 content.