cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: [doc] name for new content type?
Date Mon, 03 Jun 2002 10:38:41 GMT

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


Mime
View raw message