Contact for managing Fedora documentation?

[Karsten Wade]

On Tue, Jan 20, 2009 at 11:31:49AM +1000, David O'Brien wrote:
> Comments inline...
>
> Karsten Wade wrote:
>> On Fri, Jan 16, 2009 at 10:31:54AM +1000, David O'Brien wrote:
>>
>> One of the reasons we embraced the wiki is because it greatly
>> increased the community contributions.  Be aware that limiting source
>> to DocBook XML also limits the number of contributors.
>>   
> This is one of the concerns that has been raised. We'd like to find a  
> workable middle-ground, where potential contributers are not dissuaded  
> by the requirement to learn or use a specific language, but neither are  
> maintainers, editors, etc., bombarded with content in so many formats  
> that excessive time is spent in conversions.

Having a simple system in the wiki could work, though.  MediaWiki
categorization and such; feed watches, etc.  For example, we have a
mailing list that is a bit of a firehose -- it receives all bug
traffic for 'fedora-release-notes' package; it used to receive all the
wiki changes to 'wiki/Docs/Beats'; and so on.  If you use "either wiki
(for short stuff and drafting) or DocBook (for longer stuff and
converted-from-wiki stuff), then your content community can work in
two places, see commits via one firehose, and plan sync/migration of
content.

>> This is of course without the Magic Grail that we all want -- an easy
>> way similar to a wiki or wysiwyg-via-WebUI that reads and writes to
>> valid DocBook XML.
>>   
> We need to be careful with "valid DocBook XML". What is valid for one  
> brand in publican may well not be for another brand (this is my  
> understanding - maybe Jeff can clarify). OOo may also output "valid  
> XML", but it will fail to build using the RedHat brand. However, I  
> understand the sentiment; the ability to write in <my fav. language>  
> using <my fav. editor> and being able to output xml suitable for the  
> brand and toolchain we're using would give me warm fuzzies. :)

Hmm.  I'm not sure how to apply that.  In my mind, there _is_ such a
thing as valid DocBook XML.  We may have toolchains with expectations
on how the toolchain wants it to behave, that is not per the
standard.  I understand why Publican et al make limitations on tags it
will accept and so forth.  The proper way to deal with this is to have
XSLT to transform between the XML expectations our toolchains have.

We shouldn't limit ourselves in planning based on the fact we don't
have an army of XSLT experts at hand. :) The more of us with a similar
itch, the more chance we'll find someone to help us scratch it.  For
example, the Google Summer of Code is upcoming ...

https://fedoraproject.org/wiki/Summer_coding_2009

> We're considering a mixture of this. We envisage an area on the wiki  
> where contributers can submit how-tos, examples of how they solved a  
> particular issue or a configuration that they used. If it's something  
> that is suitable for Enterprise doc (and not, for example, how to  
> configure unsupported hardware/software to work) then we would convert  
> it to DocBook. At present we only have full-length books, and pushing  
> back and forth between the wiki and DocBook is really not an option.

Agreed; back and forth is not viable.  The wiki is lossy; all of the
markup context is lost in conversion (or needs to be created.)

The nice thing about the Enterprise content is that it can be a fork
from an upstream source, maintained along with that version of the
product.  If you have:

* 100% fidelity of content in an area where the maximum number of
  contributors can help

* A match of versions to fork from (Free 4.0 becomes Enterprise 1.7)

* Willingness to do *all* of the work in the upstream so there can be
  clear demarcation of ongoing FreeIPA work and frozen-for-maintenance
  Enterprise IPA work.

Depending on how much changes between versions, you can actually use
the wiki diff engine to tell if there needs ot be updates to the XML.
The key is having a disciplined approach to versioning and branching.

Having a sane hosting and SCM for the document helps.  We're using
Trac + git for most Fedora guides.  We can track what happens with a
version of a document in version-specific tickets.

> This might work for the smaller contributions from the community (in my  
> project) but not for the large books (as mentioned above). The doc group  
> basically consists of me, with draft contributions from developers and a  
> (very) few community members.

The larger point I want to make is that open content is like open
source code.  You can always hire a team and accomplish a lot with
that team, but there is a limit to how far you can scale.

If you start now with community sourcing all of your content, not just
the small tutorials, then you build something that is truly low cost
and scalable, sooner rather than later.

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090120/d6c694e9/attachment.sig>