why o why

[Jeff Kinz]

On Thu, Apr 21, 2005 at 12:19:06PM +0530, Rahul Sundaram wrote:
> Hi
> 
> >
> > You can easily track changes with wiki , implement workflow and change 
> > history ...revert the changes, discuss changes  ..edit document 
> > online, resolve conflicts  and yes its possible to export wiki into 
> > docbook format do lot dynamic stuff with content ... 
> > (http://meta.wikimedia.org/wiki/DocBook_XML_export) ... 
> 
> 
> 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).

I've been using troff macros to produce docs for almost 20 years, so I'm
not afraid of directly producing clumsy non-wysiwig formats like xml.

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:

Wikipedia: picked up in less than 15 minutes.

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.  

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.


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)

Often a worked thru example is worth more than 20 pages of "documentation"


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