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.