On Sat, 2006-11-11 at 11:47 +0300, John Babich wrote:
Fedora Docs Team Members:
One area which appears to be overlooked is the installation and
updating of software by the novice user. Various sections exist (such
as the excellent one on yum - see
http://fedoraproject.org/wiki/Tools/yum),
but there is no "gentle introduction" for the person new to Fedora
Core.
If you missed this, it is mainly because we are so poorly organized at
revealing docs to users:
http://fedora.redhat.com/docs/yum/index.html
It needs updating for FC6. Being an existing guide, it is a *great* way
to dive into DocBook.
You can find it in CVS:
cvs.fedoraproject.org:/cvs/docs/yum-software-management
The layout of the module needs to be modernized; we can work with you to
make that happen, then it will build nicely and be ready for
translation.
However, a quick review of the Administration Guide reveals no
section
on the
installation and updating of packages.
Yes, it should link out to the Yum and/or new guide (which could combine
ideas).
A MODEST PROPOSAL
Oh, joy, is this where we get to cook and eat the children?
/me hopes that enough people get that literary reference :)
Therefore, I propose a separate Installing and Updating Software
Guide
aimed
at the beginning Fedora Core user. I volunteer to write and edit the
guide and
welcome any and all contributions and suggestions. (That includes a
better
name for this guide). We would start from the Fedora Core 6 release.
This assumes, of course, that I get the "go ahead" from the Powers
That Be.
Well, there aren't any PTBs around here that restrict good ideas or
require you to have permission to start new things. You could even
start from scratch instead of the existing guide, although that is not
recommended. Our main PTB role is in enabling you all to do good work,
so expect encouragement and not discouragement. :)
In other words, go for it!
PROPOSED OUTLINE FOR THE IAUSG
[snip good outline to give John a chance to compare against the existing
"Managing Software with Yum", which also needs a better title]
FLOSS AND COTS PACKAGES
Additionally, we should stick with FLOSS software and avoid packages
which violate the GPL. At the same time, we should remember that there
are legal, commercially available packages which can be covered in
general terms. Most of these commercial-off the-shelf (COTS) packages
come with detailed instructions and/or installation scripts, so this
section can be short.
This guide should follow the guidelines and policies for the Fedora
Core wiki concerning "forbidden items" (not my favorite term). See
http://fedoraproject.org/wiki/ForbiddenItems.
One important consideration for all of our work is that it should only
cover the software available in Fedora. That has always meant Core +
Extras, and nowadays that is even more relevant (as Fedora engineering
leaders go off to discuss a possible merger of Core + Extras for FC7).
By sticking with this software, we are:
* Guaranteeing that it is acceptable by Fedora standards; if it is a
Fedora package, it is legally safe to use
* Sticking by what is unique to Fedora instead of getting into battles
about outside software v. what is in the distro
* Maintaining solidarity with package maintainers
* Avoiding unnecessary work that is documented elsewhere
(Aside: Maybe we can come up with a less harsh-sounding phrase than
"forbidden items".)
Yeah, I thought that too way back when, but it's such a well publicized
page ...
Also, I like the idea of forbidden to some degree because it is not a
wishy-washy word. It puts the responsibility back onto the software for
not being compliant, instead of it being due to use being picky.
In conclusion, ala Rod Serling's Twilight Zone, this is submitted
"for
your
consideration."
Rock on. If you would like to takeover the maintainership of the Yum
guide and grow it, you are most, most welcome to do so. The original
author is no longer an active contributor, so this is a much needed
takeover.
I recommend taking the chance to work with DocBook. The hassles to work
with the Wiki then output to DocBook later, when it is already in
existence, is going to be much, much more than the learning curve for
XML. We are very interested in growing the XML expertise in this
project, as well, so you have many willing helpers here and on
#fedora-docs. If you've ever worked with HTML before, you'll find
DocBook XML cleaner and easier.
For entirely new sections/chapters that you want to add, you may want to
collaborate on them in the Wiki until you have a draft you are happy
enough with. Then we can convert it to XML, clean it up, and include it
in the docbase.
Thanks for a good idea and taking the initiative to make it happen.
Cheers - Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. |
fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\