why o why

[Jeff Kinz]

On Thu, Apr 21, 2005 at 12:59:57PM -0500, Eric Rostetter wrote:
> 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.

Correct, and wikimedia (used by wikipedia) doesn't presume anything.

> And you're not counting the time/effort to setup, manage, document,
> etc. the wiki system in the first place (for the project).

Yes, very good. it would make no sense to count any of that
since submitters would not need to know any of that. 

> > 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.

I suspect vastly more people will find it much easier to pick up wiki
than docbook. (However I am not proposing that we replace the current
system with wiki, I was just pointing out what stopped me from adding a
document)

> > 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).

Definitely stick to one.  I recommends wikipedia.

> > 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 

Correct, That was my main issue.  I would put up a small example of
creating a very very small doc  (two short paras, title, toc, list, and a
link)

> 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).

Apparently you can submit a doc in just about any format you want.  This
policy was unknown to me (Something else to put into the FDOC Guide :) )
or I would have submitted my doc in html or text format.

>  
> > 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.

Yup.

-- 
Jeff Kinz, Emergent Research, Hudson, MA.