A Modest Proposal for a New Guide

[Karsten Wade]

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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- 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/2f8c47cf/attachment.sig>