Archive the initial user readiness review
Keep the first user-readiness assessment in the repo so the GA work has a\nconcrete evaluator baseline to refer back to.\n\nAdd the existing timestamped report and document the directory convention in\nuser-readiness/README.md so future reviews can be added without guessing how\nfiles are named or what they represent.
This commit is contained in:
parent
1dc566e089
commit
511fab683a
2 changed files with 69 additions and 0 deletions
61
user-readiness/1773333303.md
Normal file
61
user-readiness/1773333303.md
Normal file
|
|
@ -0,0 +1,61 @@
|
||||||
|
• Verdict
|
||||||
|
|
||||||
|
This does not read as GA yet. For the narrow target you explicitly define, X11 desktop users on Ubuntu/Debian, it feels closer to a solid beta than a
|
||||||
|
general release: the packaging and release mechanics are real, but the first-user surface still assumes too much context and lacks enough trust/polish for wider distribution. For broader Linux desktop GA, it is farther away because Wayland is still explicitly out of scope in README.md:257 and docs/persona-and-distribution.md:38.
|
||||||
|
|
||||||
|
This review is documentation-and-artifact based plus CLI help inspection. I did not launch the GUI daemon in a real X11 desktop session.
|
||||||
|
|
||||||
|
What A New User Would Experience
|
||||||
|
|
||||||
|
A new user can tell what Aman is and who it is for: a local X11 dictation daemon for desktop professionals, with package-first install as the intended end-user path README.md:4 README.md:17 docs/persona-and-distribution.md:3. But the path gets muddy quickly: the README tells them to install a .deb and enable a user service README.md:21, then later presents aman run as the quickstart README.md:92, then drops into a large block of config and model internals README.md:109. A first user never gets a visual preview, a “this is what success looks like” check, or a short guided first transcription.
|
||||||
|
|
||||||
|
Top Blockers
|
||||||
|
|
||||||
|
- The canonical install path is incomplete from a user perspective. The README says “download a release artifact” but does not point to an actual release
|
||||||
|
location, explain which artifact to pick, or cover update/uninstall flow README.md:21. That is acceptable for maintainers, not for GA users.
|
||||||
|
- The launch story is ambiguous. The recommended path enables a systemd user service README.md:29, but the “Quickstart” immediately tells users to run aman
|
||||||
|
run manually README.md:92. A new user should not have to infer when to use the service versus foreground mode.
|
||||||
|
- There is no visible proof of the product experience. The README describes a settings window and tray menu README.md:98 README.md:246, but I found no
|
||||||
|
screenshots, demo GIFs, or sample before/after transcripts in the repo. For a desktop utility, that makes it feel internal.
|
||||||
|
- The docs over-explain internals before they prove the happy path. Large sections on config schema, model behavior, fact guard, and evaluation are useful
|
||||||
|
later, but they crowd out first-run guidance README.md:109 README.md:297. A GA README should front-load “install, launch, test, expected result,
|
||||||
|
troubleshooting.”
|
||||||
|
- The release surface still looks pre-GA. The project is 0.1.0 pyproject.toml:5, and your own distribution doc says you will stay on 0.y.z until API/UX
|
||||||
|
stabilizes docs/persona-and-distribution.md:44. On top of that, pyproject.toml lacks license/URL/author metadata pyproject.toml:5, there is no repo
|
||||||
|
LICENSE file, and the Debian package template still uses a placeholder maintainer address control.in:6.
|
||||||
|
- Wayland being unsupported materially limits any GA claim beyond a narrow X11 niche README.md:257. My inference: in 2026, that is fine for a constrained
|
||||||
|
preview audience, but weak for “Linux desktop GA.”
|
||||||
|
|
||||||
|
What Already Works
|
||||||
|
|
||||||
|
- The target persona and supported distribution strategy are explicit, which is better than most early projects docs/persona-and-distribution.md:3.
|
||||||
|
- The repo has real release hygiene: changelog, release checklist, package scripts, and a Debian control file with runtime deps CHANGELOG.md:1 docs/release-
|
||||||
|
checklist.md:1 control.in:1.
|
||||||
|
- There is a support/diagnostics surface, not just run: doctor, self-check, version, init, benchmarking, and model tooling are documented README.md:340. The
|
||||||
|
CLI help for doctor and self-check is also usable.
|
||||||
|
- The README does communicate important operational constraints clearly: X11-only, strict config validation, runtime dependencies, and service behavior
|
||||||
|
README.md:49 README.md:153 README.md:234.
|
||||||
|
|
||||||
|
Quick Wins
|
||||||
|
|
||||||
|
- Split the README into two flows at the top: End-user install and Developer/maintainer docs. Right now the end-user story is diluted by packaging and
|
||||||
|
benchmarking material.
|
||||||
|
- Replace the current quickstart with a 60-second happy path: install, launch, open settings, choose mic, press hotkey, speak sample phrase, expected tray/
|
||||||
|
notification/result.
|
||||||
|
- Add two screenshots and one short GIF: settings window, tray menu, and a single dictation round-trip.
|
||||||
|
- Add a “validate your install” step using aman self-check or the tray diagnostics, with an example success result.
|
||||||
|
- Add trust metadata now: LICENSE, real maintainer/contact, project URL, issue tracker, and complete package metadata in pyproject.toml:5.
|
||||||
|
- Make aman --help show the command set directly. Right now discoverability is weaker than the README suggests.
|
||||||
|
|
||||||
|
Minimum Bar For GA
|
||||||
|
|
||||||
|
- A real release surface exists: downloadable artifacts, checksums, release notes, upgrade/uninstall guidance, and a support/contact path.
|
||||||
|
- The README proves the product visually and operationally, not just textually.
|
||||||
|
- The end-user path is singular and unambiguous for the supported audience.
|
||||||
|
- Legal and package metadata are complete.
|
||||||
|
- You define GA honestly as either Ubuntu/Debian X11 only or you expand platform scope. Without that, the market promise and the actual support boundary are
|
||||||
|
misaligned.
|
||||||
|
|
||||||
|
If you want a blunt summary: this looks one focused release cycle away from a credible limited GA for Ubuntu/Debian X11 users, and more than that away from
|
||||||
|
broad Linux desktop GA.
|
||||||
|
|
||||||
8
user-readiness/README.md
Normal file
8
user-readiness/README.md
Normal file
|
|
@ -0,0 +1,8 @@
|
||||||
|
# User Readiness Reports
|
||||||
|
|
||||||
|
Each Markdown file in this directory is a user readiness report for the
|
||||||
|
project.
|
||||||
|
|
||||||
|
The filename title is a Linux timestamp. In practice, a report named
|
||||||
|
`1773333303.md` corresponds to a report generated at Unix timestamp
|
||||||
|
`1773333303`.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue