[Grok-dev] thoughts while writing a tutorial

[Luciano Ramalho]

On 8/17/07, Sebastian Ware <sebastian at urbantalk.se> wrote:
> What a great idea. These "trails" could be a great way to organise
> "recipes", "tutorials", "howtos", "primers", "best practices" you
> name it...

Quoting myself in a message July, 5:

"""
I liked very much Martijn's idea of "tours" as a way of modularizing
the content of our tutorial. The official Java Tutorial by Sun [1] is
organized in "trails", and except for the basic ones, the rest are
very independent of each other. It's clear to me that macros have to
be one of our tours.

[1] http://java.sun.com/docs/books/tutorial/

The Zope 3 Developer's Handbook labels each chapter according to it's
difficulty using words to describe the reader: "newcomer", "sprinter",
"contributor", "core developer". That is very useful to make it easier
for readers to jump around the chapters.

Maybe our "tours" could be labeled as well according to their audience
as well. We could have:
- "Python developer": a web developer who knows Python but not Zope 2 or 3
- "Zope 2 developer"
- "Zope 3 developer"
Some tours would be aimed at more than one audience.
"""

The idea of trails applies to organizing tutorials. What we currently
have is an assortment of texts with different characteristics, and
"recipe" is perhaps the best way to describe many of them.

All content, be it recipes, howtos, tutorials, *examples* (very
important category) should be tagged with multiple subject tags, and
not put into discrete compartments. Of course, our site has to support
this tagging (like plone does).

I also agree that the whole grok setup and grokproject stuff must be
refactored out of the several places where it appears into one
canonical recipe.

Regards,

Luciano