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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\