Potentially remove Software Reference page

[jonnew]

This page is odd to me:

• It has a very general title and very specific information.
• The information pertains to things that are not yet described.
• The information repeats content that is generated from source code comments, which are localized to the objects that they pertain to
• It is redundant and must be manually kept up to date as new data sources are added and or changed.

I feel this page should be removed. If existing descriptions are inadequate, they should be updated.

[ChucklesOnGitHub]

I see. Cris and I created this while working on the tutorials that work with the data in physical units, intending it to be a aggregate reference of all the devices at one glance. I can understand that this requires manual update and thus not sustainable, and this info should be mostly in the Reference pages. Let's not duplicate information, but rather convert this section into "How to use the Reference".

I would still keep it around until we make sure that we:

• ensure all the DataFrames currently have this information in their reference page (see e.g. Amplifier Data in NeuropixeldV2eDataFrame)
• consider having one line per spec (Bit Depth, Offset, Scale/Step Size) within each DataFrame reference Property block that needs it in order to help quick reference, instead of the current wall-of-text format. See what I mean at the end.
• map hardware to the devices they contain, linking to the Data Elements page for that device (e.g. each Hardware Guides lists fefatures of the device, but the DataFrame reference is not linked - links go to example sub-workflows instead)
• keep the other considerations on the current page, which were intended to guide unaware/inexperienced users on how to use these values. Ideally, it should be straightforward to get to physical units, and evident to the user that the software isn't doing that for them.

@cjsha can you think of any other intention we had when we created this table/page that we'd need to address in the revamp?

About the current Reference wall-of-text, my suggestion to make it more visually segmented is:

The end of each Property block in which it is relevant to provide the conversion, instead of a wall of text:

Have one spec per line, could be something along:
Bit Depth: xx-bit as xxsigned xx-bit integers.
Scale: xx
Offset: xx
To convert to xxx, use the following equation: xxx

[cjsha]

ensure all the DataFrames currently have this information in their reference page (see e.g. Amplifier Data in NeuropixeldV2eDataFrame)

This should already exist, it looks like the docs aren't pointing to the latest release of the src code. Though it's obviously not yet in the format of how you suggest in the next bullet point.

map hardware to the devices they contain, linking to the Data Elements page for that device (e.g. each Hardware Guides lists fefatures of the device, but the DataFrame reference is not linked - links go to example sub-workflows instead)

This is the only one I'm iffy on. I'm not sure this is necessary if we have a page that shows them how to navigate and find certain info in the reference page as you suggest?

can you think of any other intention we had when we created this table/page that we'd need to address in the revamp?

Yeah I mean I think we started this page before all the reference pages had the conversion equation. I/We were thinking of putting it in the published tutorial bc that's where this info was originally relevant. The tutorial uses Headstage64 but users might be using other hardware with different conversion scalars/offsets. Then we thought maybe we should have a place for this table to exist elsewhere bc it seemed like generally pertinent info outside of the tutorial. I agree a page that teaches how to navigate the reference page would be better since we're suggesting that the conversion scalars, offsets, etc. is maintained in the XML comments.

[cjsha]

jonnew and I had a discussion in which he suggested making the page that describes how to use the "Reference" section of the docs the landing page of that section. In other words, he suggested that we put info on this page: