From 511fab683a0bac43c92270e24c258e0e9aeeb2fe Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Thu, 12 Mar 2026 15:00:58 -0300 Subject: [PATCH] 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. --- user-readiness/1773333303.md | 61 ++++++++++++++++++++++++++++++++++++ user-readiness/README.md | 8 +++++ 2 files changed, 69 insertions(+) create mode 100644 user-readiness/1773333303.md create mode 100644 user-readiness/README.md diff --git a/user-readiness/1773333303.md b/user-readiness/1773333303.md new file mode 100644 index 0000000..f66a22f --- /dev/null +++ b/user-readiness/1773333303.md @@ -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. + diff --git a/user-readiness/README.md b/user-readiness/README.md new file mode 100644 index 0000000..9ef921f --- /dev/null +++ b/user-readiness/README.md @@ -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`.