Bug 967358
Summary: | fedora-easy-karma lacks usability, feedback, and documentation | ||
---|---|---|---|
Product: | [Fedora] Fedora | Reporter: | John Reiser <jreiser> |
Component: | fedora-easy-karma | Assignee: | Till Maas <opensource> |
Status: | CLOSED ERRATA | QA Contact: | Fedora Extras Quality Assurance <extras-qa> |
Severity: | unspecified | Docs Contact: | |
Priority: | unspecified | ||
Version: | 19 | CC: | ignatenko, opensource |
Target Milestone: | --- | ||
Target Release: | --- | ||
Hardware: | Unspecified | ||
OS: | Linux | ||
Whiteboard: | |||
Fixed In Version: | fedora-easy-karma-0-0.19.20130707git121694f6.fc18 | Doc Type: | Bug Fix |
Doc Text: | Story Points: | --- | |
Clone Of: | Environment: | ||
Last Closed: | 2013-07-12 02:56:43 UTC | Type: | Bug |
Regression: | --- | Mount Type: | --- |
Documentation: | --- | CRM: | |
Verified Versions: | Category: | --- | |
oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
Cloudforms Team: | --- | Target Upstream Version: | |
Embargoed: |
Description
John Reiser
2013-05-26 19:57:11 UTC
(In reply to John Reiser from comment #0) > Description of problem: The user interface of fedora-easy-karma is so > minimal that it is unfriendly and hard to use. In particular, there should > be some comment made about the expected magnitude of the task, especially > when there is "nothing to do". Also there should be a manual page with some > motivation and an example, including actual output. There is a wiki page containg this: https://fedoraproject.org/wiki/Fedora_Easy_Karma Just wondering: How did you stumble upon fedora easy karma and decided to use it? > Actual results: > $ fedora-easy-karma > Getting list of installed packages... > Getting list of packages in updates-testing... > $ echo $? ### Notice "no useful output" from "fedora-easy-karma". Why? > 0 The version in git will now report if no updates from testing were found. > $ man fedora-easy-karma > No manual entry for fedora-easy-karma > $ There is a separate bug for this. If someone provides a man page I will include it. But IMHO the wiki is a better place to document it. Since the tool requires network access, there is no downside to it. The help text now also contains a pointer to the wiki. > Expected results: > $ fedora-easy-karma > Getting list of installed packages... 3800 available; 2442 installed > Getting list of packages in updates-testing... 987 available; 0 installed > Note: repo [updates-testing] from > /etc/yum.repos.d/fedora-updates-testing.repo is not enabled. Please change > to "enabled=1" then run "yum clean all; yum update". A hint to install testing packages has been added. I do not see much value in calculating numbers of packages, but if you provide a patch I will take a look and integrate it. (In reply to Till Maas from comment #1) > There is a wiki page containg this: > https://fedoraproject.org/wiki/Fedora_Easy_Karma > Just wondering: How did you stumble upon fedora easy karma and decided to > use it? A message from kalevlember in test.org on May 25 promoted the use of fedora-easy-karma. The wiki is no good. I searched for the actual name of the command, namely "fedora-easy-karma" [without the quotation marks]. The response was a "no such page" error, and *NONE* of the suggested pages were anywhere close; the string "karma" *NEVER* appeared! So this is another example of poor usability. > <<snip>> > There is a separate bug for this [no manual page]. If someone provides a man page I will > include it. But IMHO the wiki is a better place to document it. Since the > tool requires network access, there is no downside to it. The help text now > also contains a pointer to the wiki. *EVERY* command that is intended for invocation directly by a human deserves a manual page. *NO EXCEPTIONS!!!* Just because the package creator/maintainer does not believe in manual pages does not erase decades of user training that manual pages provide the next level of documentation after --help. If nothing else, the manual page can say, "fedora-easy-karma iterates through the list of packages that are currently installed from [updates-testing], and guides the user for feedback (karma) on each package in turn. See <<insert literal URL to exact wiki page>>." The downside of relying on the wiki is that the wiki itself has poor usability. Searching is futile. The only time that searching the fedora wiki gives a reasonable answer is if you know the page title beforehand. What really angers me is that nowhere in my initial experience of using and learning about fedora-easy-karma did I encounter an explanation such as "for each package that is currently installed from the [updates-testing] repo ...", and there was no summary comment such as "You have zero packages installed from [updates-testing]". Couple that with a repeatable delay of more than two minutes with little or no activity (no CPU, no disk, no network) between the initial flurry and the final exit-with-no-results, and it is easy to see how I might wonder why such a poor experience was promoted as being a good thing. (In reply to John Reiser from comment #2) > (In reply to Till Maas from comment #1) > > There is a wiki page containg this: > > https://fedoraproject.org/wiki/Fedora_Easy_Karma > > Just wondering: How did you stumble upon fedora easy karma and decided to > > use it? > > A message from kalevlember in test.org on May 25 > promoted the use of fedora-easy-karma. The message contains a link to http://fedoraproject.org/wiki/QA:Update_feedback_guidelines which mentions the the FEK wiki page. > The wiki is no good. I searched for the actual name of the command, namely > "fedora-easy-karma" [without the quotation marks]. The response was a "no > such page" error, and *NONE* of the suggested pages were anywhere close; the > string "karma" *NEVER* appeared! So this is another example of poor > usability. I added an alias page so your search term should succeed now. Nevertheless, the wiki is the first result if you search using Google. > > <<snip>> > > There is a separate bug for this [no manual page]. If someone provides a man page I will > > include it. But IMHO the wiki is a better place to document it. Since the > > tool requires network access, there is no downside to it. The help text now > > also contains a pointer to the wiki. > > *EVERY* command that is intended for invocation directly by a human deserves > a manual page. *NO EXCEPTIONS!!!* Just because the package > creator/maintainer does not believe in manual pages does not erase decades > of user training that manual pages provide the next level of documentation > after --help. If nothing else, the manual page can say, "fedora-easy-karma > iterates through the list of packages that are currently installed from > [updates-testing], and guides the user for feedback (karma) on each package > in turn. See <<insert literal URL to exact wiki page>>." Since is the information you will get with "--help" already (the development versions contains a link to the wiki page). But if someone shows me an easy way to create a man page from the wiki page, I will include it. But it is not a high priority task for me to create one from scratch because of lack of time. But If you want to create one, I will include it. > What really angers me is that nowhere in my initial experience of using and > learning about fedora-easy-karma did I encounter an explanation such as "for > each package that is currently installed from the [updates-testing] repo But then you did not read the "--help" output, which starts as follows: | You will be asked for every package installed from updates-testing to provide | feedback using karma points. > ...", and there was no summary comment such as "You have zero packages > installed from [updates-testing]". Couple that with a repeatable delay of > more than two minutes with little or no activity (no CPU, no disk, no > network) between the initial flurry and the final exit-with-no-results, and > it is easy to see how I might wonder why such a poor experience was promoted > as being a good thing. For me it was a proof of concept that karma submission can be done easier than using the web interface. If you find other/better ways, you are free to use them. Nevertheless I added a message to it that notifies the user if no packages from updates-testing are installed. fedora-easy-karma-0-0.19.20130707git121694f6.fc19 has been submitted as an update for Fedora 19. https://admin.fedoraproject.org/updates/fedora-easy-karma-0-0.19.20130707git121694f6.fc19 fedora-easy-karma-0-0.19.20130707git121694f6.fc18 has been submitted as an update for Fedora 18. https://admin.fedoraproject.org/updates/fedora-easy-karma-0-0.19.20130707git121694f6.fc18 Package fedora-easy-karma-0-0.19.20130707git121694f6.fc18: * should fix your issue, * was pushed to the Fedora 18 testing repository, * should be available at your local mirror within two days. Update it with: # su -c 'yum update --enablerepo=updates-testing fedora-easy-karma-0-0.19.20130707git121694f6.fc18' as soon as you are able to. Please go to the following url: https://admin.fedoraproject.org/updates/FEDORA-2013-12590/fedora-easy-karma-0-0.19.20130707git121694f6.fc18 then log in and leave karma (feedback). fedora-easy-karma-0-0.19.20130707git121694f6.fc19 has been pushed to the Fedora 19 stable repository. If problems still persist, please make note of it in this bug report. fedora-easy-karma-0-0.19.20130707git121694f6.fc18 has been pushed to the Fedora 18 stable repository. If problems still persist, please make note of it in this bug report. |