GUIs: Define documentation format

[bparks13]

As we approach the release of OpenEphys.Onix1.Design 0.2.0, we will need to document the GUIs as they are being released. Below are a list of questions we should think about before diving too deep to make sure we are spending time wisely developing good documentation for them.

• What is the best way to document the GUIs? All options will be hard to maintain, since it will need to be manually generated content.
  • Should it mostly be screenshots of the screen, with squares and numbers highlighting specific sections and their actions?
  • Single screenshot of the screen, and then sections of text that describe the controls and their various functions?
  • Is it worth making small videos or GIFs to show how the GUI looks in action rather than making walls of text?
• Where will the GUI documentation live? I believe there was some discussion about these being placed under the Tutorials tab, but I am not sure if that was the final decision.
• How should we link to the underlying enums that are used in drop-down menus? Specifically, how much information do we discuss in these pages versus how quickly should we link to an existing page and say "Check out the reference over there"?
• The Design library has a number of XML comments added to the public methods and properties: should we add OpenEphys.Onix1.Design to the Reference tab so that the public methods and comments for them are available for easy access?
  • This would need to be in a new namespace, so we would have OpenEphys.Onix1 and OpenEphys.Onix1.Design as the first heading division, and then the existing TOC structure for OpenEphys.Onix1. Might be more trouble than it's worth to bring this in and format it accordingly.

[bparks13]

@jonnew @cjsha let me know if you discussed anything else this morning that might be relevant to this discussion. Please add more questions as they come up.

[cjsha]

We didn't really discuss this topic. Here are my thoughts.

We should structure it like a reference moreso than a linear tutorial. More concretely, I would make a single screenshot with several numbers and highlighted fields with a section underneath that describes what those numbered and highlighted things are. If the entire GUI is not capturable in a single screenshot, there can be more than just a single screenshot. Basically what you describe here:

Single screenshot of the screen, and then sections of text that describe the controls and their various functions

Is it worth making small videos or GIFs to show how the GUI looks in action rather than making walls of text?

I like the idea of embedded animated gifs or webps. I think GUIs are visual things and is easier to straight up display visual things than trying to describe them with text. Their disadvantage compared to video is that they can't be paused. In any case, this would probably contained in a tutorial wherein we are showing the user how to accomplish a particular task with the GUI.

Where will the GUI documentation live? I believe there was some discussion about these being placed under the Tutorials tab, but I am not sure if that was the final decision.

I think the breakout board tutorials will strongly define how the rest of the tutorials looks, so the final answer to this question depends on those tutorials end up looking. However, in the meanwhile, this is how I imagine it would be organized:

Tutorials
    Breakout Board
        Breakout Board Tutorial 1
        Breakout Board Tutorial 2
        ...
    Headstage64
        Headstage64 Tutorial 1
        Headstage64 Tutorial 2
        ...
    Neuropixelsv2eHeadstage
        Neuropixelsv2eHeadstage GUI
        Neuropixelsv2eHeadstage Tutorial 1
        Neuropixelsv2eHeadstage Tutorial 2
        ...
    ...

To specifically answer your question, the GUI has its own entry in the TOC under the corresponding hardware.

How should we link to the underlying enums that are used in drop-down menus? Specifically, how much information do we discuss in these pages versus how quickly should we link to an existing page and say "Check out the reference over there"?

We shouldn't describe anything that's automatically generated. We can link to enum pages which are still being hosted and served. They're just not in the toc.

The Design library has a number of XML comments added to the public methods and properties: should we add OpenEphys.Onix1.Design to the Reference tab so that the public methods and comments for them are available for easy access?

I do see a case for including it in these docs, imo under the "Reference" tab, under the "OpenEphys.Onix1" dropdown, under "Other" dropdown. I think only namespaces that contain searchable operators in Bonsai should exist as first-level dropdowns. However, I think it would deserve its own set of issues and a milestone for a date that's an order of magnitude further away

[bparks13]

This is fantastic, thank you for the thoughts @cjsha! I agree with everything, except I'm not convinced that hiding the Design library under the Other dropdown is the best. The GUI will be a huge part of the functionality for a lot of these operators, and I think it should be more visible. For Bonsai libraries, each namespace is at the top-most level (for example, see the Bonsai.Design library). This approach makes sense to me because the namespace is a top-level item, it is what differentiates the two libraries from each other.

[bparks13]

Another question that came to mind is how do we point people to the GUIs from the base operator page? Originally I had some language in a template that described how to interact with a GUI, but with the (highly needed) updates to the pages those templates have been removed. Adding some boilerplate language and then inserting the relevant link to the correct GUI tutorial I think will be the simplest to implement.

[cjsha]

I made an issue #38 re: OpenEphys.Onix1.Design docs for discussing later unless you think it's important for documenting 0.2.0.

I agree. We can add that as {{{conceptual}}} content into the base operator page.

[bparks13]

See #41 for how the first GUI page is formatted. Until we reorganize the docs, I think we should follow that format.