why o why

[Paul W. Frields]

On Thu, 2005-04-21 at 12:50 -0400, Jeff Kinz wrote:
> 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.

I think what you're indicating is not necessarily as indicative of
problems in the toolset as of problems in the guide.  The latter should
be fixed before we move on the former.

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

The example-tutorial is sorely lacking.  However, what people (including
myself) fail to notice is that the Documentation Guide itself is
guidance.  When an author follows the three-step process to download the
fedora-docs source from CVS, you get the XML source code to the very
Documentation Guide you're reading online.  Once the author realizes
this, *everything* gets easier.  I troubled around for, well, quite a
bit longer before this bit of slightly recursive logic occurred to me.

That's not to say that my experience shows a solution; it merely
indicates a way in which the Guide could be improved to actually solve
the problem.  We could solve this problem in much the way that the Emacs
online tutorial works -- in other words, making the CVS downloading, and
reading some XML part of a real tutorial process.  But that's only one
solution; I am still in favor of eventually moving to a (stable and
dependable!) GUI tool to ease newbies into the process.

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

I could not agree more.  From my previous life as an instructor, I'm a
big believer in "tell me, then show me, but most importantly let me do
it."

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050421/d1acbc07/attachment.bin