Docs Meeting Notes for 2025-05-27

[glopesdev]

Existing issues

• Demo of full stack from acquisition to analysis
• Proposal for site reorganization and revamp harp-tech.github.io#23

Needs

• Manuals for individual pieces of hardware as opposed to emphasizing too much the general infrastructure
  • Go into detail on the role of each register in each board and what they can be used for
  • Provide examples
• Down to the point manuals with detailed installation notes on how to turn on the devices
  • Open Ephys acquisition board as example: https://open-ephys.github.io/acq-board-docs/
• Website landing page
• Entry points for people using each device:
  • Link in vendor website, e.g. OEPS store
  • View help in Bonsai
  • QR code packed with devices
• Mono repo vs device-specific websites:
  • common website / entry point for each device + companion detailed website with internal datasheets
  • inspiration for common website could come from the CF version
• Schematics in examples is very useful, e.g. https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/DIOInput/DIOInput.html
• Start with one exemplar device and attempt to flesh out the entire docs scaffolding / content / infrastructure

Proposal

• Host docs under harp-tech.org
• Full control should go to who is writing the docs, i.e. direct commit and push updates
• Consider Sphinx / rST as the backbone of the device / frontend website (potentially with DocFX somewhere on the reference site)
• Theme to be decided

[glopesdev]

One issue with switching to rST / Sphinx which is worth emphasizing is a significant migration cost from people who are already inside the harp-tech ecosystem and have learned DocFX to learn and migrate to a different system. There are ways to prepare rST to look and feel and edit very similar to Sphinx, so would be nice to have as an action point the exact list of pain points with markdown that are currently a blocker for this.