A Modest Proposal for a New Guide

[Karsten Wade]

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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061111/96cc2af5/attachment.sig>