A Modest Proposal for a New Guide

Paul W. Frields stickster at gmail.com
Mon Nov 13 19:58:51 UTC 2006


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
-------------- 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/20061113/3bac70e2/attachment.sig>


More information about the fedora-docs-list mailing list