why o why

[Eric Rostetter]

Quoting Jeff Kinz <jkinz at kinz.org>:

> > I suspect that learning how a wiki system manages all this would have a
> > similar learning curve to using CVS and Docbook.  We really should be
> 
> I have to disagree, strongly. those learning efforts are different by at
> least an order of magnitude, possibly two.  You cannot presume
> familiarity with either xml or docbook technology on the part of the
> contributors. (or even CVS).

Nor familiarity with wiki, or exporting/importing from/to wiki, etc.
And you're not counting the time/effort to setup, manage, document,
etc. the wiki system in the first place (for the project).

> However, the difference in scale of effort required to learn how to use
> a good wiki (like the one wikipedia is using), and the amount of effort
> required to learn the XML/Docbook/Fedora docbook template is vastly
> different.  Speaking from personal experience:

Yes.  I had a much harder time learning to use a wiki than learning
to use XML/DocBook. :)  That doesn't mean your opposite experience is
of no value.  You and I just had different experiences.
 
> Wikipedia: picked up in less than 15 minutes.

I've been trying to learn to use wiki's for almost a year now and there
is still more I don't know about them than there is that I do know about
them (perhaps because I'm trying to use too many different wiki's, all
of which lack sufficient documentation on how to use them effectively).

> Fedora docs: Examined the guides, looked at all the documentation offered
> on the process.  That documentation presumed prior knowledge on how to
> use xml and docbook without providing a pathway to same.

That simply means the docs need to be improved, not that the process
much be changed (although perhaps the process should be changed, but
that is a separate issue).

> Result:
> 	20 min in wiki = finished submission of existing document
> 	2 hrs in fedora docs - given up as too clumsy to be worth the
> 	effort to convert existing document.

I imagine that would be true for many.  But for some of us (me), the
opposite would be true also.

That's really why I'd like to see both methods available (wiki for those
who want it, with someone who will export from the wiki to DocBook
for submission manually).
 
> How to fix it/ Whats missing from fedora docs guide:
> 	No example of simple Fedora docbook document being created
> 	pointers to Fedora docbook templates and skeletons
> 	(please note - if these already exist, then they need to be
> 	better advertised)

I agree.  But this is simply a documentation issue, not a process issue.
 
> Often a worked thru example is worth more than 20 pages of "documentation"

A worked through example is documentation (whether 20 pages or not).

-- 
Eric Rostetter