A Modest Proposal for a New Guide

[John Babich]

Rahul:

Rahul Sundaram wrote:

> This was one of the guides that I was planning on updating into a
> "software package management guide" covering Yum, Pirut and Pup. I would
> prefer to work on the wiki.

I also prefer working with the wiki for the reasons I listed below:

>> POINT #2 - INTEGRATING THE YUM GUIDE INTO WIKI CONSIDERED
>> 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.

At the same time, I can see the value of a DocBook version which can be
incorporated into a Fedora Core handbook. I personally want to master
DocBook
XML and Emacs since they are such popular and powerful tools.

The good news is that I think we can have both wiki and DocBook
simultaneously.

IMHO we all need to be reminded form time to time that there are two reader
audiences with which we are attempting to communicate:

1. The Fedora "newbie" - This is the person who wants to use Fedora as a
    desktop replacement, but doesn't know or care about the internals of
Linux,
    Gnome or Nautilus, at least in the beginning. This person takes his car
to
    a mechanic for regular maintenance.

2. The Fedora "power user" - This is a former newbie, a developer or a
person
    who enjoys "hacking" in the best sense of the word, figuring out how
Fedora
   works "under the hood". To continue the automotive analogy, this person
   changes her own oil. This person reads the detailed specs and pours over
   the engine schematics.

I see the wiki as the easier method to get timely information out in a
consistent
manner to both the newbie and power user.

The wiki even allows the newbie to participate in the process, which
explains the
popularity of the wiki format in the first place.

I see DocBook XML as the means to producing the technical reference handbook

for the power user and developer.

Both methods result in output which can be easily accessed and indexed if
done
properly. The wiki can be the "mind mapping" tool with the DocBook as the
more
systematic, comprehensive output.

Ideally, the cool wiki-DocBook conversion tools can continue to be refined
further so
that the choice is to have both available, each with their intrinsic
advantages, with
a minimum of manual editing.

>> POINT #5 - THE YUM GUIDE (PARTIALLY) DIGESTED
>> 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".

Like the DUG,  the perspective should be from the desktop first. The desktop
user
encounters "Add/Remove Software" and "Software Updater" functions, not yum,
pirut or pup. Unlike the DUG, the user has access to the root password and
can
be encouraged to explore the CLI utilities. I envision the DUG as the
beginner's
guide, with the new guide aimed more at the intermediate/advanced level.

Bottom line: I volunteer to edit and help write a new section in the wiki.
Let's
call it

"Installing and Updating Software - a Software Package Management Guide".

I will concentrate on the outline and will aim to keep it clear enough for
the
newbie. It will be divided into sections covering yum, pirut and pup. As the
guide
develops, intermediate and advanced topics will be introduced and explored.
I hope other experienced writers such as yourself will contribute their
insights
and expertise.

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