[packagekit] Documentation

[Matthias Clasen]

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:

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.

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.

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).

- 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".

- 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"


Matthias