General approval before publishing first phase

[ChucklesOnGitHub]

We'd appreciate a general check to make sure the first version of these docs is ready to get published online. Even though there is ongoing work to expand these docs, they are helpful as is so we'd like to get them online by August.

All the current headstages are finished, and we will move on to adapters and eibs and other headstages and remaining details as per the Issues that are open.

There is some overlap with existing content, but:

• regarding the google sheets original channel map tables: These docs are meant to be complementary to the google sheets, which are linked in the docs, and are still helpful to keep in table format. The main point of these docs is that they locate the channel numbers on the physical view of the devices. This cuts the need for multiple steps by the user. We would link to and from the sheets.

• regarding the headstage specifications table within these docs. We actually want to keep only the fields that are relevant for the channel maps: Acquisition System, REF and GND, Source Files and Release.

All other content would be included in the corresponding hardware docs for each headstage. We don't yet have hardware docs for the SPI headstages, so we kept it here until we do. We will then migrate the headstage specs table to each hardware docs. Those docs could include all the devices and vias included on each headstage, which are more than just a table.

We do not want to duplicate content to casue maintenance pain -we already have duplicated content in some hardware and software docs for onix headstages.

[jonnew]

I am assinging @bparks13 for a general review since I'm OOO and this needs to be taken care of.

[bparks13]

Since this is a general review, and not tied to a specific PR yet, I will leave my comments here. Some of these are admittedly nitpicky, but good to be aware of before publishing in case we want to discuss any changes. Overall I think it is coming along nicely! I unfortunately cannot comment on how useful it is for a user with hardware in their hands to figure out their channels, as I don't have any experience with that step, but I can at least help with the rest of the look-and-feel of the docs site.

Home page

• Weird indentation (actually, it seems like this indentation is used throughout the site; is this intended?)

• The cards for the EIBs and adapters are commented out on the main page, but they are still listed in the opening line; might be best to state explicitly that they are coming soon, or remove references to them to avoid confusion
• “Usage Manuals for each device are in the documentation sites of their respective acquisition systems.”
  • “Manuals” → “manuals”
  • Currently this is not a very helpful sentence, but could be incredibly useful. I would expand on what is trying to be said here, specifically by adding details on where exactly to find usage
    • Such as, “For X headstage in Y acquisition system using Z software, check out LinkX LinkY LinkZ”. This does not need to be done for all of them, but a few worthy examples would go a long way
  • I know we are trying to find the line between maintaining duplicate code and being useful, but I think on the home page especially we can expand on some of these details to make sure we point users to the correct places
• There is no local TOC in the right sidebar for the index.html files, and the spacing of the elements looks like something is missing. This is probably related to the html_sidebars option in the conf.py file (see OE GUI docs for reference in the second image)

Headstage pages:

• Discovered some weird behavior with the “Back to top” functionality and the Sheets embedded in the page (this is true for at least the first four headstage pages); the page will scroll back to the top unintentionally following the set of steps below
  • To reproduce: In my local build, scroll down to the bottom, and then scroll up a little bit (just enough to have the “Back to top” appear), then click inside the embedded sheet (the exact location is sometimes not 100% reproducible, but clicking on the cell headers [‘A’, ‘B’, etc.]) has a very high probability of triggering the “Back to top” button
  • Additionally; a secondary way to reliably trigger this behavior has been found; scroll down, then scroll up so that the button appears, then click on another window to change the focus, then click back to the docs page. Clicking almost anywhere on the page leads to it scrolling back to the top
  • Clicking on an image, and then hitting the back button also leads to the page scrolling to the top
• Is it possible to also add a link out directly to the spreadsheet instead of just embedding it? This would be useful for at least two reasons; 1) if the page is constantly scrolling up to the top whenever a user is trying to find their information it would be very annoying, and 2) while nice to have all in one page, navigating through the spreadsheet is much easier when it is full screen and not embedded in the docs repo
• There is a lot of wasted vertical space due to the white space embedded in a lot of the images. Can we remove the white space or find some way to reduce the amount of scrolling needed on each headstage page?
• Additionally, with just images and image captions it is sometimes hard to tell what exactly I’m looking at, and it also makes it hard to tell if the caption goes to the image above or below. Can we add some headers and maybe a sentence or two explaining each image so that it is easier for the user to parse?
• Each page also has two headers at the same level (H2 I believe?) which feels very redundant. If we need both the SKU and the product name, can we add these to the template so that only one header is created by concatenating the two titles?

User Guide:

• Previous page is not labelled correctly

• This should have a different name (“Home”), as it is pointing to the home page, not the Headstages page

[bparks13]

As a quick follow up, Cris showed me where the CSS file is in the repo and helped me track down where the indentation issue comes from. In the theme_overrides.css file, there is an entry:

paragraph indent
p {
  text-indent: 1em;
}

If this is removed it changes the indentation of the paragraphs so they are lined up on the left edge, which matches what we have in the other documentation repos.

[cjsha]

I wanna give some feedback too!

---

I know you want to limit the scope of these docs to channel-maps and leave all hardware related info in some other docs site. However, we could also go the other way and making these the "headstage-docs" instead of just "channel-map-docs". I don't want to derail too much, I know following this suggestion would change the target quite a bit, but I think it's worth considering

---

If you wanna put the serial number there, I would display it as a subtitle not in the same level as the header

original:                                                                     example proposal:

I think you can accomplish something like this using a rubric directive and some custom css. lmk what you think and I can help with that.

---

I noticed we put SKU and then headstage name in these card titles.

I think most people recognize the headstage name before SKU, and I think we should follow that order. For example:

from:

OEPS-7741 ONIX Headstage Ephys 64ch

to:

ONIX Headstage Ephys 64ch (OEPS-7741)

---

I feel like it's not immediately obvious what we mean by "NB: add 1 in the Open Ephys GUI"

I'm inclined to suggest adding more details in the caption. I know you mention it in the "Important Considerations" section of the User Guide, but I'm not sure everyone's gonna make it there before heading to their headstage's page.

---

When it comes to "Important Considerations", I feel like it's relevant in this section or maybe elsewhere to mention that the operating voltage that we list in these docs are the voltage as measured on the headstage, not the voltage set in software which is always higher (how much higher depending on the tether length and thickness).

---

I think the landing page could use some improvement. For sure, it should have a top-level title besides "Headstages".

---

Since the user guide consists of a single page, I propose moving it to the lading page's toc:

I know EIB and adapters are coming eventually, you can ignore that I added those and underlined them in the screenshot.

---

I know there's already an issue for this, and I think it's probably ok for the first pass, but the embedded Google Sheet is a bit clunky, so we'll have to revisit this

[magbaeta]

Thanks for the feedback and comments! I’ll get back to working on this once I’m back.

[ChucklesOnGitHub]

Let's revisit this and see if all the comments have been addressed in the issues that we've been making and closing.

[cjsha]

as far as i'm concerned, we addressed all the comments