Build human-first docs site with integrated screenshots and operator runbooks

Summary

As of 2026-04-15, the project docs need to optimize for humans running experiments, not just developers reading code. The goal is a docs site that combines step-by-step operator guidance with normal reference pages for modules/scripts/functions.

A promising shell for this is great-docs from Posit: https://github.com/posit-dev/great-docs

Documentation direction

The main docs should teach people how to use the software for real experiments:

• install and rig setup
• machine-local config
• open-loop run setup
• closed-loop run setup
• preflight workflow
• interpreting runtime UI
• troubleshooting common failure modes

Reference material should also exist, but it is secondary to the operator manual.

Important content rule

Screenshots should be integrated directly into the manual pages where they help comprehension. We do not want a separate docs/visuals bucket full of disconnected screenshots.

Candidate doc structure

• Getting Started / Windows setup
• Rig onboarding and Doric + Teensy setup
• Config guide with worked examples
• Open-loop operator guide
• Closed-loop operator guide
• Preflight walkthrough with screenshots
• Runtime dashboard guide with screenshots
• Troubleshooting
• Selected reference pages for key modules and scripts

Screenshot targets

• preflight dashboard
• preflight resize warning
• Doric selection success
• Teensy setup success
• open-loop launch summary
• closed-loop RFID assignment
• runtime waiting / active / fault states

Related tooling

scripts/ui_mock_preview.py may be useful for stable docs visuals, but it currently appears stale and needs its own evaluation/update.

Acceptance criteria

• choose docs-site approach and bootstrap structure
• define the initial information architecture
• identify which pages need real screenshots vs generated visuals
• land the first human-first operator pages before trying to document every internal detail

Start by evaluating the proposed great-docs shell and the existing scripts/ui_mock_preview.py, including whether that preview tool is stale. Define the initial information architecture and decide which listed operator pages need real screenshots or generated visuals. Done means the docs-site structure is bootstrapped and the first human-first operator pages are published before broader reference coverage.