On Thu, Apr 21, 2005 at 07:42:51PM -0400, Paul W. Frields wrote: > On Thu, 2005-04-21 at 12:50 -0400, Jeff Kinz wrote: > > 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. Spot on. That was intended to be my main point. > > 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. Aha. See what I get for trying to understand the technology before using it! :) > 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." Amen. -- Jeff Kinz, Emergent Research, Hudson, MA. -- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
