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