cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [doc] name for new content type?
Date Tue, 04 Jun 2002 09:37:06 GMT
Diana Shannon wrote:

> > I think it's a pretty cool idea to use the 'cooking metaphore': imagine
> > something like this:
> 
> I think it's very clever, as long as we are careful not to "mix"
> metaphors (e.g. with existing pipeline metaphor) too much.

Nah, I wouldn't worry about that. Those two metaphors happen at
different conceptual levels: "recipes" are a metaphor for the context of
understanding, "pipelines" are a metaphor used in the context of
applying the understood concepts.

One is inside the other.

IMO, metaphors confuse when different ones get applied to the same
conceptual context.


> > A recipe is a more compact version of an howto: you already know how to
> > cook, you just need basic instructions on what you have to do. Also,
> > there are tons of way to cook the same stuff, we can have recipes that
> > cook the same things differently.
>
> Good point, especially with Cocoon. Still, I hope, initially, we get
> lots of recipes about different things to cook.

Well, I wouldn't be surprised if this isn't the case. People will send
recipes for what they like the most or for what they found more useful.
I bet we'll have several recepies covering a few topics, way before we
have covered the full spectrum of usage.

Anyway, it's the same for cooking: if you collect recipes from your
friends, I'm pretty sure that you'll end up having a bunch for
'chocolate chip cookies' or 'stuffed turkey', and very few for "risotto
alla milanese" or "ragu' alla bolognese".

The good thing is that with my friends will be the other way around, so
there is hope :)

> > 2) a tutorial/howto (I think they should be treated the same way)
> > explain only something about that they are talking about, but they do in
> > full detail, if basic assumptions are needed, they should be referenced
> > explicitly in the howto markup so that the publishing system can create
> > hyperlinks to the requirements.
>
> I strongly disagree. I think most users would agree with me. Sometimes
> you just need a basic how-to to accomplish something. Simple steps for
> those of us with *no* time to learn something new each and every time we
> happen to do something new. It would be nice to master this or that
> concept every time we do something different, but the reality remains
> that we don't have enough time -- at least initially. Tutorials should
> teach, as well as show how. Tutorials contain how-to information but
> they also contain conceptual information. How-Tos are just the facts,
> nothing more. Tutorials help you apply knowledge to a range of problems,
> not just the problem at hand.

Got it. Many thanks for the clarification. I changed my mind and I now
perfectly agree with you.
 
> I'm approaching this very granularly. For new stuff, consider writing at
> least a few FAQS (it will save you time on Cocoon users). Also, consider
> writing a few snippets. If you have time, write a How-To. With this
> basic information, others can come along and extend your work: write
> more FAQs, snippets, and how-tos, even more complicated How-Tos (which
> link to less complicated How-Tos). Later, those with the "big picture"
> can combine some of this material into a Tutorial or Guide. Providing
> small granular ways to contribute should help users participate.

Sounds great.

What about recipes?

> I love it. Thanks a lot. I'll try to write a How-To, based on this email.

Yeah, metadocos, I love it.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message