thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Add X11 GA roadmap and milestone definitions

Browse source 
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.
This commit is contained in:
Thales Maciel 2026-03-12 13:56:41 -03:00
parent fa91f313c4
commit 01a580f359
No known key found for this signature in database
GPG key ID: 33112E6833C34679
6 changed files with 437 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

68
docs/x11-ga/04-first-run-ux-and-support-docs.md Normal file
View file

@ -0,0 +1,68 @@
# 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.