why o why

[Jeff Kinz]

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.