A Modest Proposal for a New Guide

[John Babich]

Karsten:

POINT #1 - THE EXISTING YUM GUIDE REVEALED

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

After I sent my initial email, I compiled a list of links and discovered
the existing yum guide. I saw a copyright date of 2006 and saw that it was
edited by Paul Frields et al. I assumed that the guide was being actively
maintained. Now I know differently.

You'll need to explain exactly what you mean by modernizng the module.
As for writing in DocBook XML, I'm ready to take the plunge.

POINT #2 - INTEGRATING THE YUM GUIDE INTO WIKI CONSIDERED

> Yes, it should link out to the Yum and/or new guide (which could combine
> ideas).

I would like to see the wiki continue to be integrated with other documents.

I found that I made good progress on the DUG due to the ease-of-use and low
barrier to entry. Having said that, I am ready for the next challenge,
having
fooled around with Docbook XML in EMACS for a little while now.

POINT #3 - LITERARY ALLUSION ACKNOWLEDGED

> Oh, joy, is this where we get to cook and eat the children?

I'm glad to see that you are a man of letters. In the spirit of political
correctness, my apologies in advance to my Irish friends. Jonathan Swift
could be so insensitive.

POINT #4 - PERMISSION GRANTED

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

My definition of "Powers that Be" is a pragmatic one. I like to "go with
the flow" of the Fedora Project, which means having a spirit of cooperation
with the committed team members. I will occasionally risk the wrath of the
PTB, but I hope only for good reasons. I also prefer PTB over PHBs. :)

POINT #5 - THE YUM GUIDE (PARTIALLY) DIGESTED

> [snip good outline to give John a chance to compare against the existing
> "Managing Software with Yum", which also needs a better title]
>

I think yum will continue to be the focus of the guide, but there are no
direct
references to yum (or rpm for that matter) in the Fedora Desktop. The
functional
"labels" on the desktop are "Add/Remove Software" and "Software Updater".

That's why I would like to use a generic title like "Installing and Updating

Software in Fedora".

POINT #6 - AVAILABLE FEDORA SOFTWARE RE-EMPHASIZED

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

There's plenty to do with the software packages available in Fedora Core
and Extras. I find that the Extras repository is getting very comprehensive.
In the past I would use RPMFind or Google to locate an RPM. Now I check
Fedora Extras first with a high hit rate.

POINT #7 - THE LURE OF THE FORBIDDEN RESISTED

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

I guess people need to be reminded that the GPL is one of the main reasons
projects like GNU/Linux and Fedora Core exist.

POINT #8 - THE YUM GUIDE TO BE MASTERED WITH DOCBOOK VIRTUOSITY

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

Point taken. I agree with the source living in DocBook XML with
collaboration
and easy entry via the Wiki.

POINT #9 - A CARROT AWARDED COMPLIMENTS OF KARSTEN

> Thanks for a good idea and taking the initiative to make it happen.
>
> Cheers - Karsten

POINT #10 - THE CARROT CONSUMED AND SAVORED BY JOHN

You're welcome.

John Babich
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061111/73d9aba2/attachment.htm>