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
Attachment:
pgp5OP0mImbfF.pgp
Description: PGP signature
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
