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.
<[EMAIL PROTECTED]> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
