[Grok-dev] thoughts while writing a tutorial

[Sebastian Ware]

What a great idea. These "trails" could be a great way to organise  
"recipes", "tutorials", "howtos", "primers", "best practices" you  
name it...

That would make it very accesible to users. Maybe we eventually would  
have volunteers responsible of maintaining each trail. And a  
beautiful timeline showing who contributed what and when...

Mvh Sebastian

17 aug 2007 kl. 15.51 skrev Brandon Craig Rhodes:

> Sebastian Ware <sebastian at urbantalk.se> writes:
>
>> I know it is more semantics, but I think we should call them
>> recipes, indicating that they should be kept lightweight and
>> focused.  Howtos, to me, are ways of setting up an environment.
>> Tutorials are more general and comprehensive.
>
> I agree that "How-to" generally means something much larger, and
> involves setting up an entire product (such as the Samba HOWTO, or the
> Linux Networking HOWTO).  I am not sure about "recipe", because often
> a recipe is a list of instructions, without much commentary, that you
> follow; and, at least with the tutorials I'm beginning to write, the
> point is to explain and help you understand - they often show two or
> three options for doing something, so that you can choose the one that
> fits best.
>
> So I suppose I like "tutorial" best at this point, but you're right
> that they are quite different from something like the Python Tutorial,
> that shows you everything about the language in a single document.
>
> Would it be too "cute" to extend the caveman theme?  While cavemen did
> leave cave paintings, calling these tutorials "Paintings" would be a
> bit odd.  "Cave Walls" or "Cave Scratchings" also sound pretty odd.
> The best we could probably do in the caveman direction would be to
> call them "trails", which cave men followed through the forests.
> ("You want to connect to a database?  Go read the ZAlchemy Trail.")
> It would be too cartoonish to call them "Hunts", and though cave men
> did share with each other techniques for building and honing tools
> just like the tutorials, I can't think of a good, pithy word that
> means "short guide to building or honing a particular kind of tool".
>
> -- 
> Brandon Craig Rhodes   brandon at rhodesmill.org   http:// 
> rhodesmill.org/brandon