Some thoughts on the yum tutorial

[Paul W. Frields]

On Wed, 2005-07-27 at 01:46 +0100, Stuart Ellis wrote:
> > 4. I definitely would omit the "su -c '...'" in the examples,
> > and just say you have to run yum as superuser,
> > perhaps once mentioning sudo and "su -c".
> 
> It does look inelegant.  The idea is that you can dive into the document
> at any point and get a command that works with no further explanation. 
> 
> My view is that sudo should be configured by anaconda to start with :)

Better yet, why isn't it just tied to consolehelper like other superuser
programs?  After all, there's not much you can do with yum that's really
useful unless you've got that level of access.  Then there would be no
sudo required.  I suspect this was a bit of a compromise on Seth's part.
I suppose in the future it might be possible for something like a
yum-generated dbus message that would alert the system you need
superuser access, so it could generate a consolehelper-type prompt.

> > 7. I think a brief description of how yum works -
> > eg what is meant by "metadata" and where it is stored -
> > would be useful.
> > I'd add a few words about rmp headers as well.
> 
> The term headers was explained in a previous version, I think, and
> I'll try to work it back in without too much exposition.

Let's be careful not to dump too much technical information into a
procedural guide.  This is precisely where a lot of documentation I see
on the web goes wrong -- it becomes what I call a "core dump" which has
limited additional use.  When I started teaching Linux many years ago, I
had to conquer the innate geek need to explain all the technical
minutiae, simply because of how gosh-darned cool it all is.  (And free!
Did I mention free?)  

This tutorial does not need to explain, for example, the RPM format to
teach people how to manage software on their systems.  Keep the mission
in mind at all times.  Unless information actually helps someone get the
job done, it's superfluous.  That being said, certain concepts are
irrevocably tied to understanding a procedure.  Those should remain in
the docs.

> > 8. A few words on what to do about yum errors
> > would be very useful, perhaps as a FAQ.
> 
> Hmm. Could you give an example of a specific yum error ?  I would think
> that the most common problems are likely to be general network errors.

Good point, see above!

> > 9. I would have suggested adding non-standard repositories
> > to /etc/yum.repos.d/ with enabled=0
> > using yum with enablerepo=... when desired.
> 
> This involves editing the configuration files, and I don't think that
> you get much benefit from it, to be honest.
> 
> > 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.
> 
> Further to what Paul has said, this issue came up on the yum mailing
> list last week.  The yum developers take a strong line on unsigned
> pacakges, and won't add features to make it easy for users to install
> them.
> 
> Some proprietary vendors do supply their products as individual unsigned
> packages.  For these cases, I'm not sure whether or not we should
> document: 
> 
> rpm -ivh the-vendor-is-an-idiot.1.i386.rpm
> 
> Purely as a courtesy to Fedora users.  I'm open to persuasion either
> way.

My vote's against it.  It's a very short hop for the uneducated to go
from this to "rpm -ivh --force," or worse, "rpm -e --nodeps".  ("Hey,
why should I bother with yum? It puts all that crap on my screen.")
Beyond which, I don't want to take a single step in the direction of how
to deal with proprietary vendors.  That's the best way to avoid a
slippery slope argument on why we don't document use of other non-free
software.  Let me get off my soapbox before I take that too far,
sorry.  :-)

As part of the official Voice of Fedora (sorry, getting geared up for
that "V for Vendetta" movie), we should probably toe the party line on
this one.

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