2:47 a.m.
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.
According to the Documentation Summary section of the Desktop User Guide:
<quote>
*Assumptions:* The reader has a standard Desktop class installation of
Fedora.
The reader has a user account with the default settings.The reader does *not
*
have access to the *root* password.
*Related Documents*: The
AdministrationGuide<http://fedoraproject.org/wiki/Docs/Drafts/Administ...
tasks that require
*root* access. The
GettingStartedGuide<http://fedoraproject.org/wiki/Docs/Drafts/GettingS...
a general introduction to using Fedora.
Each desktop application has integrated Help, so the scope of this document
may need to be considered carefully.
<end-quote>
I agree with the DUG assumption not requiring the novice user to have access
to the root password. This keeps the DUG focused on the basics.
However, a quick review of the Administration Guide reveals no section on
the
installation and updating of packages.
The Getting Started Guide has the following section:
<quote>
Cool Things To Do with Fedora
Everything above gives users equivalents to a standard Windows desktop that
they have seen before. What cool things can new users try with a Fedora
system that take them further ?
-
LinPhone <http://fedoraproject.org/wiki/LinPhone> - demonstrates
installing from Extras, and free phone calls. Requires: headset.
-
GnuCash <http://fedoraproject.org/wiki/GnuCash> - installs from Core,
home finance software isn't cool, but is important.
<end-quote>
However, the links for installing LinPhone and GnuCash don't link to
existing pages.
A MODEST PROPOSAL
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.
PROPOSED OUTLINE FOR THE IAUSG
These would be the assumptions for the Installing and Updating Software
Guide:
*Assumptions:* The reader has a standard Desktop class installation of
Fedora.
The reader has a user account with the default settings.The reader **hasaccess
to the *root* password. The reader has access to the internet (preferably
broadband).
The reader does not have a degree in Computer Science.
We need to give some background information and provide concepts and details
as required.
As suggested by the Getting Started Guide, we can demonstrate different
classes of
installs, such as from the Core and Extras repositories.
We should also demonstrate different methods of installing packages,
going from the simplest to the more complex.
1. Install a package like xmms using Pirut. (Perhaps xmms with fluendo?)
2. Install Yumex via Pirut, and then install (perhaps a game) via yumex.
3. Use rpm from the CLI to view a list installed packages (no root password
required).
4. Use rpm to install a locally available package (root password required).
5. Use yum to install a package from an internet repository.
6. Use yum to provide various reports.
7. Use yum to do a group-level installation, such as a complete KDE
desktop installation.
8. More advanced topics:
a. Using smart.
b. Using apt-get.
c. Using yum at installation time via the new anaconda feature.
Likewise, we should cover the topic of updating packages in a similar
progression from the simple to the advanced.
1. Update packages using Pirut.
2. Update using Yumex.
3. Update using yum from the CLI.
4. Selectively update using yum (including/excluding packages
and disabling/enabling repositories).
5. More advanced topics:
a. Do a complete Fedora Core release upgrade (I actually have done
this successfully on a laptop with a bad CD drive and broadband
internet access.)
FURTHER READING (RELATED DOCUMENTS)
As always, we should provide pointers to good links, both inside and
outside of the Fedora Core wiki.
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.
<http://fedoraproject.org/wiki/ForbiddenItems>
(Aside: Maybe we can come up with a less harsh-sounding phrase than
"forbidden items".)
In conclusion, ala Rod Serling's Twilight Zone, this is submitted "for your
consideration."
John Babich
12:25 p.m.
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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
2:31 p.m.
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
10:57 p.m.
John Babich wrote:
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.
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.
Rahul
12:19 a.m.
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
3:32 p.m.
On Sun, 2006-11-12 at 09:19 +0300, John Babich wrote:
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.
Right on John! Let me know if you need any help. As for maintenance on
the Yum guide, yes, I could use the help. Too many projects and
(lately) too little time. I would recommend starting with the DocBook
version as your jumping off place. It does need inclusion of Pirut and
Pup to get up to FC6 speed. I would really prefer that people work on
this guide rather than spinning off brand-new docs that then have to be
edited and tagged, etc., from the beginning again. (Documentation can
also suffer from "NIH" and "too many itches" syndrome.)
[...snip...]
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.
Seems to me a good starting point is porting the current guide to the
wiki and then moving on from there, then. I think the idea of "two
equal sources" for this text is currently a pipe dream. Instead, let's
think of this as temporarily moving the canonical source, with the
knowledge that there will be some re-tagging required on the way back to
the original repository:
CVS/DocBook (original repo)
-> wiki (working repo to get more juice)
-> CVS/DocBook (tagging, editing, and future work)
[...snip...]
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.
See above -- You'll have much more traction if you import what we
already have in the yum guide into the wiki. You can expect more
contribution with a more thorough coverage of the topic. And we can
worry about the DocBook porting after that, I suppose.
None of this addresses the problem of tag slippage between the wiki and
DocBook. The point of having a wiki -> DocBook converter was to get raw
content done there, port it to DocBook, and then continue in DocBook as
the canonical source for all future changes. Moving stuff from DocBook
-> wiki is a trivial problem; the reverse is practically impossible with
current tools.
If we have active contributors with enthusiasm, energy, and time, we
need to encourage them to learn the canonical tools of the trade. If
this were an art project, we wouldn't want people to spend a lot of time
producing .BMP files in MS Paint instead of helping them use GIMP and
Inkscape. Other analogies abound...
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
9:16 p.m.
New subject: Self Introduction : Ginu George
Dear Team,
I am Ginu George, working as a Team Lead for Technical Publications and
Knowledge Management, currently with Ernst & Young in India. I was documenting
software products for the last 6 years in various platforms. I think ( am not
remembering the exact nos) i did documentations for nearly 80 projects and
reviewed and edited other 200 projects.
Rightnow am doing RHCE, to make me confident in Linux. I would like to
initiate
a Free Documentation Foundation (http://www.freedocumentation.org) for
documenting and archiving all the free
software/open source products documents, which includes Users Guide,
Installation and Configuration, Knowledge Bases, Training Manuals,
Maintanance,
Operations Management etc. This in my long term plan to make all free software
manuals to be available for general public for free and keep on updating with
new relases. I hope so many people will come up to join this initative, so we
can edit and maintain that later. (this is long term plan)
This is going to be my third initative and the second one, KnowGenesis
(knowgenesis.org and knowgenesis.net) is a great success. Stallman is one of
our Advisor for the International Journal for Technical Communication. For
KnowGenesis we are training people in the field of Technical Communication and
Knowlede Management to make the foundation a helping hand in open research and
free media iniatives.
Regards
Ginu George
ginu(a)ginugeorge.com
1:12 a.m.
On 11/13/06, Paul W. Frields <stickster(a)gmail.com> wrote:
See above -- You'll have much more traction if you import what
we
already have in the yum guide into the wiki. You can expect more
contribution with a more thorough coverage of the topic. And we can
worry about the DocBook porting after that, I suppose.
I am fine with using the yum guide as a basis for the "Installing and Updating
Software Guide". I've only done a few basic pages, so it's no big deal for
me
to start over at this point.
Do we need any permission to "move" it from the Redhat site to the wiki?
None of this addresses the problem of tag slippage between the wiki
and
DocBook. The point of having a wiki -> DocBook converter was to get raw
content done there, port it to DocBook, and then continue in DocBook as
the canonical source for all future changes. Moving stuff from DocBook
-> wiki is a trivial problem; the reverse is practically impossible with
current tools.
I found references to a DocBook->wiki conversion tool in the Summer of
Code section. I couldn't find any instructions on how to perform this function.
Can you do this or give me pointers on how it can be done?
John Babich
11:46 a.m.
On Sun, 2006-11-12 at 09:19 +0300, John Babich wrote:
I see the wiki as the easier method to get timely information out in
a
consistent
manner to both the newbie and power user.
As long as that newbie can read and understand English. The Wiki is not
going to be easily connected into the Fedora translation system.
The wiki even allows the newbie to participate in the process, which
explains the
popularity of the wiki format in the first place.
Think of this in relation to Fedora development. The Wiki is a bit like
rawhide or a test release. Yes, it can be canonical documentation, but
it is ultimately harder to work with for a reader -- can't be printed,
subject to unannounced change, not translated, can contain content that
has not been tested thoroughly, etc.
We mitigate this with having two namespaces, Docs/ and Docs/Drafts.
Ultimately, just like with the distro, anything that is important to
have a version in time that ties to a version of the distro must be in
DocBook XML.
A major goal of this project is to automate from the Wiki. You would be
able to push a "Publish draft" button that:
1. Converts from Wiki -> XML, inserts XML into CVS
2. Builds XHTML from the XML, which is just the XML from CVS that might
have been edited and commited from the Wiki, Emacs, Vi, Jedit, etc.
* Also builds RPM, nochunks (one page) HTML, TGZ/ZIP of XHTML, PDF,
TXT
3. Publishes the XHTML via CMS (Plone) into various channels:
* Raw draft (akin to rawhide/devel)
* Full draft (akin to Fedora test release)
* Versioned (akin to full Fedora release or package update)
4. Links in RPM, nochunks (one page) HTML, TGZ/ZIP of XHTML, PDF, TXT
We are actively working on making that happen, more programming help is
definitely needed ASAP. :)
I see DocBook XML as the means to producing the technical reference
handbook
for the power user and developer.
With DocBook, we can put our guide in the System > Help menu or be a
part of the yum package. The guide can be right on the desktop, and
updated regularly just like any package. We cannot do that with the
Wiki.
This is why I have been pushing to make the Wiki an editor one can
choose (Emacs, Vi, OO.org, Wiki, etc.) rather than a format choice (Wiki
v. XML).
So, short answer is, yes, you are doing the right thing, especially if
you are willing to help with the conversion when the time comes. Better
to capture contributors via the Wiki so the tools aren't (perceived as)
a barrier to helping.
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.
Essentially, yes. The Wiki emphasizes collaboration over
readability/usability.
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.
Or total automation. :)
- Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
1:53 p.m.
On Mon, 2006-11-13 at 10:12 +0300, John Babich wrote:
On 11/13/06, Paul W. Frields <stickster(a)gmail.com> wrote:
> See above -- You'll have much more traction if you import what we
> already have in the yum guide into the wiki. You can expect more
> contribution with a more thorough coverage of the topic. And we can
> worry about the DocBook porting after that, I suppose.
I am fine with using the yum guide as a basis for the "Installing and Updating
Software Guide". I've only done a few basic pages, so it's no big deal for
me
to start over at this point.
Do we need any permission to "move" it from the Redhat site to the wiki?
Absolutely not, it's really *our* space anyway. You are free to use it
however you wish. Consider this a "copy" operation for now, and we'll
copy your updates over in the near future, God willing and the creek
don't rise.
> None of this addresses the problem of tag slippage between the
wiki and
> DocBook. The point of having a wiki -> DocBook converter was to get raw
> content done there, port it to DocBook, and then continue in DocBook as
> the canonical source for all future changes. Moving stuff from DocBook
> -> wiki is a trivial problem; the reverse is practically impossible with
> current tools.
I found references to a DocBook->wiki conversion tool in the Summer of
Code section. I couldn't find any instructions on how to perform this function.
Can you do this or give me pointers on how it can be done?
I think we only finished the other side of that conversion (wiki -> DB),
but this side is actually less difficult. Do you mind checking around
the lazyweb to see if someone else has done it already?
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
1:58 p.m.
On Mon, 2006-11-13 at 09:46 -0800, Karsten Wade wrote:
On Sun, 2006-11-12 at 09:19 +0300, John Babich wrote:
> I see the wiki as the easier method to get timely information out in a
> consistent
> manner to both the newbie and power user.
As long as that newbie can read and understand English. The Wiki is not
going to be easily connected into the Fedora translation system.
Thank goodness Karsten is around to bring up the really big stuff. I
seem to always miss the forest for the trees. :-) Yes, this is another
super-big argument in favor of CVS + DocBook. It would be even bigger
(airtight?) if we had a better linkup with Translation for this work.
> The wiki even allows the newbie to participate in the process,
which
> explains the
> popularity of the wiki format in the first place.
Think of this in relation to Fedora development. The Wiki is a bit like
rawhide or a test release. Yes, it can be canonical documentation, but
it is ultimately harder to work with for a reader -- can't be printed,
subject to unannounced change, not translated, can contain content that
has not been tested thoroughly, etc.
We mitigate this with having two namespaces, Docs/ and Docs/Drafts.
Ultimately, just like with the distro, anything that is important to
have a version in time that ties to a version of the distro must be in
DocBook XML.
A major goal of this project is to automate from the Wiki. You would be
able to push a "Publish draft" button that:
1. Converts from Wiki -> XML, inserts XML into CVS
2. Builds XHTML from the XML, which is just the XML from CVS that might
have been edited and commited from the Wiki, Emacs, Vi, Jedit, etc.
* Also builds RPM, nochunks (one page) HTML, TGZ/ZIP of XHTML, PDF,
TXT
3. Publishes the XHTML via CMS (Plone) into various channels:
* Raw draft (akin to rawhide/devel)
* Full draft (akin to Fedora test release)
* Versioned (akin to full Fedora release or package update)
4. Links in RPM, nochunks (one page) HTML, TGZ/ZIP of XHTML, PDF, TXT
We are actively working on making that happen, more programming help is
definitely needed ASAP. :)
Yes, it is. This is a sizable piece of work, and no one has stepped up
to claim it in the Infrastructure team. We can give guidance but very
few people around this subproject have the l33t h4cking skillz to
actually build this stuff.
Another idea for the Plone toolset just occurred to me. I'll make a new
thread to avoid derailing this one.
> I see DocBook XML as the means to producing the technical
reference
> handbook
> for the power user and developer.
With DocBook, we can put our guide in the System > Help menu or be a
part of the yum package. The guide can be right on the desktop, and
updated regularly just like any package. We cannot do that with the
Wiki.
This is why I have been pushing to make the Wiki an editor one can
choose (Emacs, Vi, OO.org, Wiki, etc.) rather than a format choice (Wiki
v. XML).
So, short answer is, yes, you are doing the right thing, especially if
you are willing to help with the conversion when the time comes. Better
to capture contributors via the Wiki so the tools aren't (perceived as)
a barrier to helping.
Yup, just look at this as the "li'l ones playset"... Emacs and DocBook
XMl are what the big kids use.
> 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.
Essentially, yes. The Wiki emphasizes collaboration over
readability/usability.
And all that that entails... ;-)
> 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.
Or total automation. :)
See next thread... ;-)
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
2:23 p.m.
New subject: Self Introduction : Ginu George
On Sun, 2006-11-12 at 21:16 -0600, ginu(a)ginugeorge.com wrote:
Dear Team,
I am Ginu George, working as a Team Lead for Technical Publications and
Knowledge Management, currently with Ernst & Young in India. I was documenting
software products for the last 6 years in various platforms. I think ( am not
remembering the exact nos) i did documentations for nearly 80 projects and
reviewed and edited other 200 projects.
Excellent, welcome.
Rightnow am doing RHCE, to make me confident in Linux. I would like
to
initiate
a Free Documentation Foundation (http://www.freedocumentation.org) for
documenting and archiving all the free
software/open source products documents, which includes Users Guide,
Installation and Configuration, Knowledge Bases, Training Manuals,
Maintanance,
Operations Management etc. This in my long term plan to make all free software
manuals to be available for general public for free and keep on updating with
new relases. I hope so many people will come up to join this initative, so we
can edit and maintain that later. (this is long term plan)
This is going to be my third initative and the second one, KnowGenesis
(knowgenesis.org and knowgenesis.net) is a great success. Stallman is one of
our Advisor for the International Journal for Technical Communication. For
KnowGenesis we are training people in the field of Technical Communication and
Knowlede Management to make the foundation a helping hand in open research and
free media iniatives.
Thank you for joining us. Fedora is very interested in being both
upstream and downstream providers of content. In the downstream case,
we want to contribute in meaningful ways back up to common documentation
bases. Right now we can do that by e.g. editing documentation from
upstream. We are not actively doing this as a group, but could be.
Tools would help here.
As upstream providers, we want to provide a common Fedora documentation
base that can be reused for Fedora derivatives. Additionally, we are
providing a Fedora-based toolchain that is a full documentation editing
system (SCM + Wiki + XML + CMS) ... doing that one piece at a time.
This sounds compatible with your ideas and activities, perhaps?
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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
6396
days inactive
6398
days old
11 comments
5 participants
participants (5)
-
ginu＠ginugeorge.com -
John Babich -
Karsten Wade -
Paul W. Frields -
Rahul Sundaram