Proposal for site reorganization and revamp

[banchan86]

This meta-issue summarizes ongoing offline discussions about revamping the Harp-Tech documentation website.
Disclaimer: This is a WIP proposal and still needs input from other members of the Harp-Tech community.

Motivation

The current Harp-Tech documentation website is a solid technical reference of the Harp protocol for Harp device designers as well as software interface developers. However, it is not very user friendly and lacks critical information for consumers of Harp devices. In its absence, different resources have sprung up to provide this information including:

• CF.Harp which provides an index of CF devices.
• CF.Bonsai which provides examples for CF devices.
• AIND.Bonsai which provides an index and technical reference for AIND devices.
• AIND Harp Workshop which provides tutorials on using some Harp devices.

Keeping the current state of affairs risks fragmenting the Harp ecosystem, degrades the consumer experience, and increases the support burden for device designers and distributors.

Proposed Solution

Convert the current Harp documentation website into a centralized portal similar to the landing page of the Bonsai-Rx website, with links to different pages with different resources.

Consumers would benefit specifically from:

• A less intimidating landing page (Protocol details should be lower on the page or somewhere else entirely #21).
• Information on Harp devices (Create index of devices #22).
• Simplified guides/tutorials and examples (Tutorials link on navigation bar is broken #16).
• Link to community resources (e.g. GitHub discussions).

In addition, there are key information currently missing from the website that would be useful to everyone who is interested in the Harp ecosystem, such as:

• A good explanation/overview of the motivation behind Harp as well as various aspects of the Harp "platform".
  • As a concrete example, the links for protocols and hardware templates dump people directly into the specification which is not a great entry point to onboard anyone.
• List of contributors and partners as well as contributions and a brief history of Harp (Contributor and About page #24)

Mockup of proposed site revamp Online preview unavailable temporarily due to Harp Hobgoblin tutorials.

Alternative Solution

Keep the current website as it is, but create a separate documentation website oriented towards consumers of Harp devices. This remains a viable solution, but it is unclear:

• who would be responsible for maintaining this separate website.
• what devices it would cover.
• whether it would simply add on another link to the growing list of support resources.

In addition, there might be duplication of some content that would be useful for everybody.

SRM Discussions

SRM 03-04-2024 - Initial discussion
SRM 15-05-2025 - Additional feedback
SRM 22-05-2025 - Additional feedback
Docs meeting 27-05-2025 - Additional feedback