thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/x11-ga/04-first-run-ux-and-support-docs.md
Thales Maciel acfc376845
Close milestone 4 with review evidence 
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.
2026-03-12 18:57:57 -03:00

3 KiB
Raw Permalink Blame History

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.