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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
