[packagekit] Documentation

[Rahul Sundaram]

Matthias Clasen wrote:
> On Mon, Mar 31, 2008 at 6:18 AM, Richard Hughes <hughsient at gmail.com> wrote:
> 
>>  Can anyone else think of what information _users_ needs to know about
>>  the gnome-packagekit tools?
> 
> I agree that it is a good start. Here are some ideas for improvement:

[Thanks for suggestions]

> 
> Conceptually:
> 
> - I think it would be good to have at least a superficial explanation
> of the PackageKit architecture and its advantages - ie the fact that
> you can start a long-running update/installation and log out without
> risking an inconsistent system. Or the fact that operation are queued
> up, and multiple users don't lock each other out.

How does all this happen?


> On the application list:
> 
> At least pk-install-file (what runs when you double-click an rpm) and
> pkcon (versatile commandline interface to PK) should be mentioned in
> addition to whats already there.

Wasn't there a discussion about unifying pk-install-file and 
pk-install-package? I will cover pkcon.

> 
> For pk-application:
> 
> - explain the meaning of the icons (installed/uninstalled), ideally
> showing the right icon in the docs (might be hard wrt to icon themes,
> not sure if yelp supports that).

Yelp supports screenshots.

> 
> - the various filters are worth explaining, I'm not sure many people
> will understand "development" vs "end user files", and the "free"
> filter begs for a link to the Fedora licensing page, or some other
> page explaining what we consider "free".

I was planning on asking this before. What is the canonical definition 
of "free" here? FSF free?

> 
> - the various "search by" options are worth pointing, out, in
> particular since they are somewhat hidden.
> 
> For pk-update-viewer:
> 
> - I think we need to explain what "refresh" means vs what "update" means.
> 
> - For the review page, the docs should explain the metadata that can
> appear in the details view, ie CVEs, bug links, etc.
> 
> - For the progress screen, we need to explain the difference between
> "Close" and "Cancel".
> 
> - The "Restart now" button/hints need to be mentioned.
> 
> 
> For pk-update-icon:
> 
> - The various notifications and activity indications should perhaps be
> explained. "If you see  [image] this bubble, run for the exit..."
> 
> - For the bubbles, it is also worth explaining how one gets them back
> after clicking on the "don't warn me again" button.
> 
> 
> Maybe some troubleshooting/faq section would be good too:
> 
> - "The icon never shows up for me. What now ?"
> 
> - "I clicked on "don't warn again", and now I can't get the bubbles back."
> 
> - "When I double-click on this package, I get a progress dialog, but
> nothing is installed"

Will look into all this. One more question as asked in IRC earlier. How 
long is long is pk-prefs?


Rahul