cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geoff Howard <>
Subject RE: Generator How-To
Date Mon, 05 Aug 2002 14:02:12 GMT
Thanks for the encouragement - I'll keep going on it as a Tutorial.  As
there is no How-To author a Tutorial, I assume that I can just sort of
follow the other examples as long as I validate against the DTD?  I have
been doing a build docs every few sections to see how things look.  


> -----Original Message-----
> From: Diana Shannon []
> Sent: Monday, August 05, 2002 9:10 AM
> To:
> Subject: Re: Generator How-To
> On Thursday, August 1, 2002, at 03:17  PM, Geoff Howard wrote:
> > As I've begun work on this, I think I'm realizing that this 
> would be 
> > better
> > as a tutorial, or an addition
> > to the Extending Cocoon section of the existing docs.
> I think your draft is *excellent*. I would classify it as a tutorial. 
> Clearly you appear to be taking the time/space to explain the 
> conceptual 
> issues behind the examples. In my opinion, How-Tos primarily 
> show "how" 
> to do something, as quickly and concisely as possible. Their primary 
> goal is expediency: to save users time, to help get the job done. 
> Tutorials, on the other hand, add in a teaching/concept component. In 
> other words, they provide the skills and knowledge to extend the 
> learning to solve other problems (extend other generators for other 
> problems). You are also providing multiple examples, from simple to 
> complex, building up a user's skill level. I'd classify that 
> as tutorial 
> material as well.
> I prefer tutorials to new core docs. I'd like to keep 
> contributions as 
> granular as possible, so they can stand on their own (without 
> dependencies to other docs). That way, as time progresses, we 
> can build 
> meaningful learning trails to tie everything together in multiple, 
> useful ways. Instead of a single user guide and a side collection of 
> FAQs, How-Tos, Tutorials, we'd have many, many learning tracks, 
> depending on a user's background and existing skill set.
> Thanks a lot Geoff. Can't wait to read the rest!
> -- Diana

View raw message