[Grok-dev] thoughts while writing a tutorial

[Brandon Craig Rhodes]

Two weeks ago I promised a tutorial on using SQLAlchemy from Grok,
after getting positive feedback about some example code I posted,
which used a custom traverser to instantiate the ORM objects to which
the user was trying to navigate.  Martijn mentioned that there was
another possible technique for traversing: creating a custom container
class.

Martijn's comment made me realize that I actually need to write *two*
tutorials!  The idea of traversing to an object that does not exist in
the ZopeDB is a whole subject on its own, completely separate from the
question of how one uses "zalchemy" from Grok.  Traversing to
non-ZopeDB objects has all kinds of uses, from generating dynamic
mash-ups to creating on-the-fly search results; and trying to explain
custom traversal and custom containers at the same time as "zalchemy"
would, I now think, get everything confused.

So now I am busy writing a simple first tutorial on navigation to
objects that are not persistent in the ZopeDB, but which are created
on-demand when the user tries to look at them.

Some questions have come up that I need guidance on.

 - What should I call this sort of object?  Several names suggest
   themselves, but I want to use just one main one through the
   tutorial:

    "On-demand objects"?
    "Dynamic objects"?
    "Non-persistent objects"?
    "Non-ZopeDB objects"?
    "Ephemeral objects"?
    "Transient objects"?

 - I note that every tutorial starts with boilerplate about
   "easy_install grokproject" and running "grokproject" to create the
   project and how to start the server and create a first instance of
   the application.  Is repeating this information each time the right
   approach?  Or should we have a short "Starting a Grok Application"
   tutorial that the others can reference?  ("For this tutorial, start
   by creating a Grok instance named 'Foo' whose application you
   instantiate at '/footest'.  See *link-to-the-page* if you have not
   yet learned how to do this.")

 - Tutorial authors might like having a way to test-render their
   tutorials before they submit them to see what they would look like
   on the Grok site; that way, we can debug the refactored text and
   see if our markup makes sense.

 - It would also be nice to be able to "get back to" the refactored
   text later once the tutorial is up on the web, so that we could
   submit patches against our original texts as we continue to improve
   them.  I know that I will want to continue improving the tutorial
   as my understanding of Grok impoves!

 - Why do we call them "tutorials" on the mailing list but "How-to's"
   on the web site? :-)

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon