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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
