You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Diana Shannon <sh...@apache.org> on 2002/06/01 13:35:28 UTC
[doc] name for new content type?
I'm about to introduce a new category of community contributions, code
snippets. I'm struggling with a name. Here's my own suggestions:
snippet (expanded in titles to code snippets)
recipe (expanded in titles to Cocoon code cookbook recipes)
code (expanded in titles to code samples)
Any suggestions? I like snippet the best so far, but does that work for
non-native English speakers?
Thanks.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] name for new content type?
Posted by Mattam <ma...@netcourrier.com>.
Le Sat, 1 Jun 2002 07:35:28 -0400, Diana Shannon a écrit:
>I'm about to introduce a new category of community contributions, code
>snippets. I'm struggling with a name. Here's my own suggestions:
>
>snippet (expanded in titles to code snippets)
>recipe (expanded in titles to Cocoon code cookbook recipes)
>code (expanded in titles to code samples)
>
>Any suggestions? I like snippet the best so far, but does that work for
>non-native English speakers?
>
That works for non-natives, and it is is common use in mails with <snip/> (even for french language messages).
My +1 for snippet.
--
"Not only is there no God, but try finding a plumber on Sunday. " - Woody Allen
MaT|TaM (http://mattam.ath.cx)
Re: [doc] name for new content type?
Posted by Peter Royal <pr...@apache.org>.
On Monday 03 June 2002 05:07 am, Stefano Mazzocchi wrote:
> 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.
I also like the recipe metaphor. One of my favorite perl books is the Perl
Cookbook (http://www.oreilly.com/catalog/cookbook/).
It assumes you already know perl but if you don't do it every day (like me)
its very handy. Has simple little routines such as "how to process every file
in a directory" and such. It could almost be looked at as a set of
application building blocks.
My only caveat would be that all recipies with the same purposes be grouped
together, but I'm sure that's already a consideration :)
-pete
--
peter royal -> proyal@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] name for new content type?
Posted by Diana Shannon <sh...@apache.org>.
On Tuesday, June 4, 2002, at 05:37 AM, Stefano Mazzocchi wrote:
>
>> 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?
Oops. I didn't *intend* to leave it out... it's just so new, not
permanently fixed in my mental model yet. Don't worry. I love it.
I also neglected to mention dynamic examples found in distribution. I'd
also like to develop dynamic how-tos and tutorials, learning tools with
hooks to webapp functionality (only in distro). My idea is that a
dynamic howtos/tutorials would use resources like slash-edit to check
the work of people walking through a learning process. Resulting files
could be written to directories, governed by sub sitemaps e.g., where
learners could incrementally build up the desired result of their
howto/tutorial. It wouldn't work for all topics, but it might prove
useful for others.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] name for new content type?
Posted by Stefano Mazzocchi <st...@apache.org>.
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.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] name for new content type?
Posted by Diana Shannon <sh...@apache.org>.
On Monday, June 3, 2002, at 05:07 AM, Stefano Mazzocchi wrote:
> Diana Shannon wrote:
>>
>> I'm about to introduce a new category of community contributions, code
>> snippets. I'm struggling with a name. Here's my own suggestions:
>>
>> snippet (expanded in titles to code snippets)
>> recipe (expanded in titles to Cocoon code cookbook recipes)
>> code (expanded in titles to code samples)
>>
>> Any suggestions? I like snippet the best so far, but does that work
>> for
>> non-native English speakers?
>
> Hmmm, maybe it's my italian blood, but I like 'recipe' better.
>
> 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.
>
> Recipe - PDF printable version of your documents
>
> Difficulty: ***
>
> Ingredients:
> - FileGenerator
> - TraxTransformer
> - FOPSerializer
> - RequestParameterSelector
>
> Requirements:
> - basic knowledge of XSL-FO
> - knowledge of your documents schemas
>
> [and so on]
>
> which is, IMO, much more appealing than a simple code snippet.
>
> This said, I don't think that one eliminates the other: I see this range
> of doc complexity:
>
> - book
> - tutorial (a.k.a. howto)
- howto
> - recipe
> - snippet
> - faq
IMO, how-to and tutorial are *different*. See below.
>
> 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.
>
> Anyhow, maybe it's just because I really love cooking and learning new
> ways of doing things.
>
> So, what are the differences between the above 'ways' of giving
> information? depth and knowledge assumptions.
Context of use. Time availability. Frequency of use.
> 1) a book gives you everything. I consider a book the organic collection
> of all our user-guide documentation. Or those printed books that are
> coming out.
>
> 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.
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.
> 3) a recipe will focus on what it's not obvious to do. Cooking recipes
> say things like "salt and pepper as you wish", they don't need to
> speficy that if you use too much salt or pepper you are going to ruin
> the dish. Just like a cocoon recipe should not tell you how to restart
> your machine or where to put your files or how to connect them into the
> sitemap. It assumes you know what you're doing.
OK.
> 4) a code snippet is a code fragment that might be helpful to show a
> concept. I consider it a bigger FAQ answer than a smaller recipe. Very
> little context is provided since the reader knows how to interpret the
> snippet.
>
> 5) a FAQ answer is normally a brief description of something that might
> point you to something more specific (maybe a code snippet).
>
> What do you think?
I love it. Thanks a lot. I'll try to write a How-To, based on this email.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] name for new content type?
Posted by Stefano Mazzocchi <st...@apache.org>.
Diana Shannon wrote:
>
> I'm about to introduce a new category of community contributions, code
> snippets. I'm struggling with a name. Here's my own suggestions:
>
> snippet (expanded in titles to code snippets)
> recipe (expanded in titles to Cocoon code cookbook recipes)
> code (expanded in titles to code samples)
>
> Any suggestions? I like snippet the best so far, but does that work for
> non-native English speakers?
Hmmm, maybe it's my italian blood, but I like 'recipe' better.
I think it's a pretty cool idea to use the 'cooking metaphore': imagine
something like this:
Recipe - PDF printable version of your documents
Difficulty: ***
Ingredients:
- FileGenerator
- TraxTransformer
- FOPSerializer
- RequestParameterSelector
Requirements:
- basic knowledge of XSL-FO
- knowledge of your documents schemas
[and so on]
which is, IMO, much more appealing than a simple code snippet.
This said, I don't think that one eliminates the other: I see this range
of doc complexity:
- book
- tutorial (a.k.a. howto)
- recipe
- snippet
- faq
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.
Anyhow, maybe it's just because I really love cooking and learning new
ways of doing things.
So, what are the differences between the above 'ways' of giving
information? depth and knowledge assumptions.
1) a book gives you everything. I consider a book the organic collection
of all our user-guide documentation. Or those printed books that are
coming out.
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.
3) a recipe will focus on what it's not obvious to do. Cooking recipes
say things like "salt and pepper as you wish", they don't need to
speficy that if you use too much salt or pepper you are going to ruin
the dish. Just like a cocoon recipe should not tell you how to restart
your machine or where to put your files or how to connect them into the
sitemap. It assumes you know what you're doing.
4) a code snippet is a code fragment that might be helpful to show a
concept. I consider it a bigger FAQ answer than a smaller recipe. Very
little context is provided since the reader knows how to interpret the
snippet.
5) a FAQ answer is normally a brief description of something that might
point you to something more specific (maybe a code snippet).
What do you think?
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: [doc] name for new content type?
Posted by Steven Noels <st...@outerthought.org>.
> snippet (expanded in titles to code snippets)
+1
</Steven>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org