[Grok-dev] thoughts while writing a tutorial

[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