Setting up FC3 this weekend I noticed that the Keeping Up to Date tutorial written for the FC2 version of yum, and is fairly terse. So I've written up a more comprehensive tutorial on up2date and yum.
I think that this is complete (perhaps too complete ?), so I'm submitting it for review -
HTML:
http://www.se.clara.net/fedora/software-management-en/index.html
DocBook:
http://www.se.clara.net/fedora/software-management-0.1.tar.gz -- Stuart Ellis s.ellis@fastmail.co.uk
--- Stuart Ellis s.ellis@fastmail.co.uk wrote:
Setting up FC3 this weekend I noticed that the Keeping Up to Date tutorial written for the FC2 version of yum, and is fairly terse. So I've written up a more comprehensive tutorial on up2date and yum.
this is nice. a few points
provide screenshots wherever applicable. I would like the whole document filled with it to look like a tutorial
you should explain old yum behavior too which doesnt have invidual repos and probably the advantages of this setup as a note
explain yum remove and put a warning on rpm -ivh section not to force install packages unless they know what they are doing clearly.
what happened to the installation guide btw. I was hoping it would be in the final form when fc3 was finished. if you arent revising it alteast push for its inclusion in the current form with screenshots so that we can revise it later on. the mailing lists are frequently filled with questions about installation and it would nice to just point them to the installation guide instead of answering the same stuff repeatedly. I have just lost count of how many times I have posted the release notes to the list. it has finally been added to the docs section.
regards Rahul Sundaram
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Meet the all-new My Yahoo! - Try it today! http://my.yahoo.com
--- Stuart Ellis s.ellis@fastmail.co.uk wrote:
Setting up FC3 this weekend I noticed that the Keeping Up to Date tutorial written for the FC2 version of yum, and is fairly terse. So I've written up a more comprehensive tutorial on up2date and yum.
this is nice. a few points
provide screenshots wherever applicable. I would like the whole document filled with it to look like a tutorial
you should explain old yum behavior too which doesnt have invidual repos and probably the advantages of this setup as a note
explain yum remove and put a warning on rpm -ivh section not to force install packages unless they know what they are doing clearly.
what happened to the installation guide btw. I was hoping it would be in the final form when fc3 was finished. if you arent revising it alteast push for its inclusion in the current form with screenshots so that we can revise it later on. the mailing lists are frequently filled with questions about installation and it would nice to just point them to the installation guide instead of answering the same stuff repeatedly. I have just lost count of how many times I have posted the release notes to the list. it has finally been added to the docs section.
regards Rahul Sundaram
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? The all-new My Yahoo! - Get yours free! http://my.yahoo.com
On Tue, 16 Nov 2004 15:18:42 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
this is nice. a few points
provide screenshots wherever applicable.
The general advice is actually to avoid screenshots wherever possible. I think that this may be to reduce maintenance. The Installation Guide is exceptional, AFAIK.
you should explain old yum behavior too which doesnt have invidual repos and probably the advantages of this setup as a note
I've now added notes about the older versions of yum to the configuration and repository sections.
explain yum remove and put a warning on rpm -ivh section not to force install packages unless they know what they are doing clearly.
Good point - I've added the warning. What extra explanation do you feel is needed for yum remove ?
what happened to the installation guide btw. I was hoping it would be in the final form when fc3 was finished.
Until recently the Installation Guide was really just a collection of chapters that I put into Bugzilla, several sections are unwritten or have outstanding FIXMEs. The issue is that the advice in the Guide must be good, so it has to be tested - particularly for things that can fail in complicated or dangerous ways like upgrades or partitioning.
At the moment I need to check the text against the final release of FC3, integrate the screenshots provided by Colin Charles and tidy up various other bits before doing another build. After that, the sections relating to partitioning and RAID are probably the most critical missing pieces.
I had to revise all my yum notes for FC3 final, so I thought that I'd put some more effort in and try to produce a proper guide. Hopefully this is now complete.
the mailing lists are frequently filled with questions about installation and it would nice to just point them to the installation guide instead of answering the same stuff repeatedly.
I know what you mean. It was the experience of providing support on a forum that finally pushed me to start writing documentation. -- Stuart Ellis s.ellis@fastmail.co.uk
Hi
The general advice is actually to avoid screenshots wherever possible. I think that this may be to reduce maintenance. The Installation Guide is exceptional, AFAIK.
in general we should favor end users over maintainers. can fedora docs teamt reconsider this advice. while it might be true for previous redhat or current redhat el releases, fedora aims are different and we should be more accomodating.
Good point - I've added the warning. What extra explanation do you feel is needed for yum remove ?
well yum remove as is the same for other operations asks for confirmation before doing removing the packages. Also unlike rpm -e, it can reverse resolve dependencies. You should be providing working examples of every command rather than simply stating them. add a note somewhere to refer to man pages and yum -h for more options and help
At the moment I need to check the text against the final release of FC3, integrate the screenshots provided by Colin Charles and tidy up various other bits before doing another build. After that, the sections relating to partitioning and RAID are probably the most critical missing pieces.
I suggest you present the installation guide to the users mailing list with a warning that its in a draft stage and collect all feedback from the huge amount of newbies there. This will get you much better understanding of what users want from a guide like this . I suspect most of us in the docs have enough experience with this to actually put ourselves in a newbie perspective
I had to revise all my yum notes for FC3 final, so I thought that I'd put some more effort in and try to produce a proper guide. Hopefully this is now complete.
its a great start but probably requires a couple of revisions. a few more points
Have a section to explain how to get rid of the alerts icon. Its a memory hog currently and is one of the FAQ's
the section on managing up2date channels should mention that up2date can *use* both apt and yum repositories but not act as a general frontend for either of these commands
7. Authorizing Package Sources
This section might have a few references to explain what gpg is(gnupg is the actual package) and also a warning against disabling gpg keys while letting the users know that there is a option to do so.
"8.1. Automatic Updates"
" There is no separate yum service. The command given above enables the yum control script in /etc/rc.d/init.d/. This control script activates the script /etc/cron.daily/yum.cron, so that the cron service will perform the system update as part of it's daily schedule."
users typically dont care how this works. if you need to explain this please do so as note. the dummies series of book does this well. it has humour titles like "techno whizbang" or something like that which clearly gets the point across that this is not a required reading. You might want to add that cron is a task scheduler for Linux
"yum provides MTA"
this is actually a meta package and probably requires a explanation as note
" The Website for the official Fedora Extras repositories is here:
this is actually a temporary status(hopefully). You might want to link to http://fedora.redhat.com/participate/terminology.html
"12. Adding Repositories as Package Sources"
It would be useful to add that one of the advantages of the new format is that a new repository can be added as a rpm package. for example freshrpms does this. Also try adding a warning that users shouldnt mix random repositories together
freshrpms and dags are not compatible with fedora.us and livna (I am not very sure of the exact details)
" Do not use the options to override this dependency checking. Instead, use yum to find and install the packages needed to meet the dependency requirements."
do not use the options to override dependancies unless you are an expert. Use yum or download the required packages manually. use rpmfind.net to find the package having the required dependancy if a package is not explicitly suggested
"You will need to install the Development Tools group of packages on your system in order to compile software from source code."
you might explain yum groupinstall and how to use the cds here. the warning can also add the information that compiling software from random untrusted sources are potentialy dangerous
reminder: for more details users should read the man pages and do explain every command with live examples
Try presenting the result to users list for more feedback
note:
This feedback might sound critical but I have been doing such tech reviews for LDP for sometime and its a good document regardless of this. Congrats
regards Rahul Sundaram
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Meet the all-new My Yahoo! - Try it today! http://my.yahoo.com
-
Rahul Sundaram -
Stuart Ellis