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 359b5fbaf4 Land milestone 4 first-run docs and media 
Make the X11 user path visible on first contact instead of burying it under config and maintainer detail.

Rewrite the README around the supported quickstart, expected tray and dictation result, install validation, troubleshooting, and linked follow-on docs. Split deep config and developer material into separate docs, add checked-in screenshots plus a short WebM walkthrough, and add a generator so the media assets stay reproducible.

Also fix the CLI discovery gap by letting `aman --help` show the top-level command surface while keeping implicit foreground `run` behavior, and align the settings, help, and about copy with the supported service-plus-diagnostics model.

Validation: `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui`; `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`; `python3 -m py_compile src/*.py tests/*.py scripts/generate_docs_media.py`; `PYTHONPATH=src python3 -m aman --help`.

Milestone 4 stays open in the roadmap because `docs/x11-ga/first-run-review-notes.md` still needs a real non-implementer walkthrough.
2026-03-12 18:30:34 -03:00

3 KiB
Raw 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.
  • A reviewer walk-through from someone who did not implement the docs rewrite.
  • A short list of first-run questions found during review and how the docs resolved them.