[Grok-dev] thoughts while writing a tutorial

[Darryl Cousins]

Hi,

On Thu, 2007-08-16 at 23:31 -0400, Brandon Craig Rhodes wrote:
> 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.

Your grok buildout should contain bin/grok2html (cretainly it will from
svn checkout of grok trunk). This executes doc/grok2html.py, add your
new tutorial to the files that are built near bottom of that script. And
then run:

bin/grok2html path/to/html

This html directory may be the checkout from svn.zope.org/grok/www which
you could update with new html if you wish.

> 
>  - 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!

No problem. Check in updated .txt file to svn.zope.org/grok/trunk/doc
and let the list know. You can also checkin the rendered html to
svn.zope.org/grok/www. I have permissions to log in to server and `svn
update` the www directory for the website.

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

Good call. Which should it be?

Regards,
Darryl

>