Thales Maciel
acfc376845
Record the independent reviewer pass that closes the first-run UX/docs milestone and archive the raw readiness report under user-readiness. Clarify the README quickstart by naming the default Cmd+m/Super+m hotkey, and align the roadmap plus release checklist with the independent-review closeout wording while keeping milestones 2 and 3 open pending manual validation. Validation: PYTHONPATH=src python3 -m aman --help; PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui; user-confirmed milestone 4 validation.
68 lines
3 KiB
Markdown
68 lines
3 KiB
Markdown
# Milestone 4: First-Run UX and Support Docs
|
|
|
|
## Why this milestone exists
|
|
|
|
Even if install and runtime reliability are strong, Aman will not feel GA until a first-time user can understand it quickly. This milestone makes the supported path obvious and removes author-only knowledge from the initial experience.
|
|
|
|
## Problems it closes
|
|
|
|
- The current README mixes end-user, maintainer, and benchmarking material too early.
|
|
- There is no short happy path with an expected visible result.
|
|
- The repo has no screenshots or demo artifact showing that the desktop workflow is real.
|
|
- The support and diagnostics story is not yet integrated into first-run documentation.
|
|
- CLI help discoverability is weaker than the documented command surface.
|
|
|
|
## In scope
|
|
|
|
- Rewrite the README so the top of the file is end-user-first.
|
|
- Split end-user, developer, and maintainer material into clearly labeled sections or separate docs.
|
|
- Add a 60-second quickstart that covers:
|
|
- runtime dependency install
|
|
- portable Aman install
|
|
- first launch
|
|
- choosing a microphone
|
|
- triggering the first dictation
|
|
- expected tray behavior
|
|
- expected injected text result
|
|
- Add a "validate your install" flow using `aman doctor` and `aman self-check`.
|
|
- Add screenshots for the settings window and tray menu.
|
|
- Add one short demo artifact showing a single install-to-dictation loop.
|
|
- Add troubleshooting for the common failures identified in milestone 3.
|
|
- Update `aman --help` so the top-level command surface is easy to discover.
|
|
- Align README language, tray copy, About/Help copy, and diagnostics wording.
|
|
|
|
## Out of scope
|
|
|
|
- New GUI features beyond what is needed for clarity and supportability.
|
|
- New branding or visual redesign unrelated to usability.
|
|
- Wayland onboarding.
|
|
|
|
## Dependencies
|
|
|
|
- Milestone 1 support contract.
|
|
- Milestone 2 install/update/uninstall flow.
|
|
- Milestone 3 diagnostics and recovery model.
|
|
|
|
## Definition of done: objective
|
|
|
|
- The README leads with the supported user path before maintainer content.
|
|
- A 60-second quickstart exists and includes an expected visible result.
|
|
- A documented install verification flow exists using diagnostics.
|
|
- Screenshots exist for the settings flow and tray surface.
|
|
- One short demo artifact exists for the happy path.
|
|
- Troubleshooting covers the top failure classes from milestone 3.
|
|
- Top-level CLI help exposes the main commands directly.
|
|
- Public docs consistently describe service mode, manual mode, and diagnostics.
|
|
|
|
## Definition of done: subjective
|
|
|
|
- A first-time evaluator can understand the product without guessing how it behaves.
|
|
- Aman feels like a user-facing desktop tool rather than an internal project.
|
|
- The docs reduce support load instead of creating new questions.
|
|
|
|
## Evidence required to close
|
|
|
|
- Updated README and linked support docs.
|
|
- Screenshots and demo artifact checked into the docs surface.
|
|
- An independent reviewer pass against the current public first-run surface.
|
|
- A short list of first-run questions found during review and how the docs resolved them.
|