Some thoughts on the yum tutorial

[Paul W. Frields]

Thanks for your comments, Timothy, they are appreciated.  I'll let
Stuart address the content part of this, but:

On Tue, 2005-07-26 at 11:42 +0100, Timothy Murphy wrote:
> 0. I found the general approach slightly over-formal
> even perhaps a tiny bit unfriendly.
> But that is just a personal view.

Official FDP material is, by nature, a bit more formal than what a lot
of readers are used to seeing from third-party sites or venues like
FedoraNews.  We have fairly comprehensive style guidelines, and try to
adhere to them whenever possible.  Doing so reduces translation
problems, adds to reader comprehension, and increases consistency in our
documentation process.  My personal predilection is for our work to look
a lot like the language used in the old Red Hat Linux documentation,
which is definitely a bit more formal, but easy to read, understand, and
translate to other languages.

> I would have put the "Revision history" as a link,
> perhaps just leaving the date of the latest revision,
> and the author or authors.

This is generated as part of our current DocBook stylesheets, but maybe
there's a way to make it come out as part of an appendix instead.  Does
anyone have any clues about this?

> 10. I think yum GPG keys cause more confusion than you realise.
> I would have mentioned the possibility of turning off key-checking
> in case one cannot find the key -
> of course as a second-best solution.

I would not recommend that, nor do I think would any of our
security-conscious writers.  :-)  GPG signatures on your packages ensure
that you are not receiving tampered copies.  Turning off GPG key
checking increases your system's vulnerability, and is not a good idea.
If you can find us some information on common yum/GPG problems, it might
be possible to write some of that into a troubleshooting section.  But
as an official documentation group, we should be *extremely* cautious
about telling anyone to decrease their security measures.

Your other suggestions may have a good deal of merit; I'll leave it to
Stuart as the author to consider them and post his thoughts.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050726/02d937ec/attachment.bin