A Modest Proposal for a New Guide

[Paul W. Frields]

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
-------------- 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/20061112/ae9321b9/attachment.sig>