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 01a580f359
Add X11 GA roadmap and milestone definitions 
Capture the current GA gaps and define a portable X11 support contract so the release bar is explicit for mainstream distros.

Document five ordered milestones covering support policy, portable install/update/uninstall, runtime reliability and diagnostics, first-run UX/docs, and GA validation/release evidence.

Left generated artifacts (src/aman.egg-info) and prior readiness notes uncommitted.
2026-03-12 13:56:41 -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 or notification 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 release or 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.