[SoaS] [IAEP] Sugar on a Stick Documentation Joins the Stage

[Karsten Wade]

On Wed, Feb 17, 2010 at 04:40:29PM +0100, Sebastian Dziallas wrote:
> Sebastian Dziallas wrote:
>> Martin Langhoff wrote:
>>> On Wed, Feb 17, 2010 at 3:53 PM, Sebastian Dziallas<sebastian at when.com>   wrote:
>>>> I've taken some hours last weekend to spend some time to finally get
>>>
>>> Very cool. What's the build line? I perused the XML looking for "how
>>> to reproduce soas builds" ;-) but it's understandably not there yet.
>>
>> Hehe! :)
>>
>> That should be: publican build --format=html --lang=en-US
>>
>> publican lives here: https://fedorahosted.org/publican/
>>
>>> The documentation I did read is very good -- but there is something
>>> makes I wonder about -- what's the advantage of this over a wiki? The
>>> barriers of entry to editing this guide are *very* high, specially for
>>> documentation people...
>>
>> Yeah, I see that point clearly. I believe the major advantages for using
>> this over wikis when creating guides or release notes is that we can
>> create a variety of formats just by adjusting one line (i.e. try
>> s/html/pdf or s/html/epub) and the ability to translate it easily.
>>
>> Translating stuff in the wiki sucks. Admittedly, I'm no translator nor
>> have I tried it with publican, yet. But from looking at how Fedora's
>> doing it, it should be pretty straight forward.

Right.  Where we have had no good success maintaining wiki
translations, the tools and methods for translating from DocBook XML
have matured nicely over the years.  Transifex.net, the translation
hosting platform, was originally started as part of fedoraproject.org,
and we continue to use the toolchain for translators.

>>> (I am a formet git developer, and have no prob with docbook... but I
>>> still find wikis more inviting...)
>>
>> Yup, they're certainly more inviting. Heh, I'm not even really
>> experienced with docbook and figured most of the stuff out last weekend.
>>
>> So what I think might be reasonable would be to use the wiki as the
>> source for content, where thoughts are gathered and stuff, and to create
>> the actual guides which are published later using publican.
>
> ...actually, kudos to quaid for this idea. :)

I came in to doing free content as a tech writer in love with the
power and flexibility of DocBook.  I came to love the different power
and flexibility of the wiki, and have worked over the years to find
ways to blend them.

Our current model is that any content needing community sourcing, such
as the release notes for each Fedora release, are sourced via the
wiki.  At specific intervals, that content is converted to XML for
translation.  It puts a bit of pain on the documenters to make it
easiest for contributors from the development side and the translators
from the other side.

One reason I encouraged Sebastian to used Publican is that makes it
easy to have the SoaS Guide be part of the formal Fedora 13 guide
set.  It will get more attention for editing and translation, and be
part of the noise we make about new and updated content for Fedora
13.  It's really similar to a feature -- the document owners decide
what is good enough to freeze by the freeze dates, or choose to
continue on and have translations handled later.

A final point - if you build on the tools and processes that Fedora
Documentation follows, you can gain some of the work going on
currently in the wider Fedora Project.  We've been working to roll out
Zikula, a CMS, for Fedora Marketing project called 'Fedora Insight',
and when that is done, the similar setup will be put under
docs.fedoraproject.org.  We're looking to integrate Beacon, which is a
web-based wysiwyg editor that was expanded last summer in a GSoC
effort to edit the relevant subset of DocBook XML that Fedora Docs
uses.

This brings us closer to the best of all worlds -- a web-based editor
that is easier to use than a wiki, inviting more contributions, that
keeps the content in XML on the backend.

- Karsten
-- 
name:  Karsten 'quaid' Wade, Sr. Community Gardener
team:                Red Hat Community Architecture 
uri:               http://TheOpenSourceWay.org/wiki
gpg:                                       AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.sugarlabs.org/archive/soas/attachments/20100217/77923bd4/attachment.pgp