[Grok-dev] Re: "Transient Objects" tutorial

[Philipp von Weitershausen]

Brandon Craig Rhodes wrote:
>  - I can't wait until the fix for the Zope bug I filed makes it into a
>    production version (thanks to PvW for shepherding the issue!)
>    because that will make the tutorial much simpler - whole sections
>    of explanation and code near the bottom can disappear!  The issue
>    about which I speak is:
> 
>      https://bugs.launchpad.net/zope3/+bug/139044

Guess why I wanted you to get checkin rights *evil laughter* :). The fix 
seems to be quite obvious now. You only need to write some appropriate 
tests to exercise it and you're ready to check it into zope.traversing. 
Please make sure you check it in at both the trunk and the 3.4 branch. 
Don't forget adding a note with a reference to the issue in the changelog.

>    On what kind of schedule do these sorts of fixes turn up in the
>    code which the average tutorial reader gets when they run
>    "grokproject"?

We'd have to make a new zope.traversing bugfix release. I can do that 
once your fix is checked in.

>  - The tutorial needs to link to a generic how-to-run-grokproject-and-
>    set-up-an-app page.

You could link to that section in the tutorial? 
http://grok.zope.org/tutorial.html#setting-up-grokproject

>  - The tutorial seems to do far too many things for a single tutorial.
>    Do you remember those folks a few weeks ago who were suggesting
>    that our site should have "recipes" instead of just "tutorials"?
>    And do you remember me disagreeing with them?  Well, I am
>    reconsidering!  I feel that this tutorial should really a small
>    "Guide to Transient Objects" that links to four different
>    "Recipes", one for each of the four basic methods.  It makes the
>    document so long to have all of the examples in-line!

First of all, thanks for writing this tutorial. As soon as I find the 
time, I'll be happy to review it, also from the perspective of splitting 
it up. As a general gut reaction, I'd say that smaller texts are better 
because they work better with the shorter attention span of us 
Neanderthals :).

>  - I feel sorry for the people who actually try out the code in this
>    tutorial rather than just reading it.  Think of all the cutting and
>    pasting, and creating and deleting files, and then getting down
>    near the bottom of the tutorial and finding something is broken
>    because they missed an insertion or deletion they were supposed to
>    do!  And then they might have to start the whole tutorial again
>    from the top to figure out what their example app should look like
>    by the time they're done.
> 
>    So I wish that ReST gave me some way of marking a series of quoted
>    Python code so that the user could click on a little icon and get a
>    .tar.gz of that particular example, ready to run inside of a Grok
>    instance.  If this tutorial were broken into four shorter and more
>    reasonable "recipes", then maybe each could have a single button to
>    download the whole example app?

Well, or you could actually put the working code example *next* to the 
reST file and use the .. include directive (with :literal:) to include 
the files. That way you can always easily tar up the examples and ship 
them (or eggify them or whatever).

>  - It would be neat if they could skip having to "create the app"
>    through the Grok interface.  Everyone who I show Grok too finds
>    that terribly weird anyway.

Yeah. With this I think Grok is showing its legacy with Zope 2 (like, 
how you have to create a Plone Site oject to run Plone, etc.). I 
actually think it would be very cool if you could say: take this 
particular grok.Application object and make it my root folder.

We should discuss this in a separate thread, though.

>  - It would be neat if there were also a way to mark up the tutorial
>    so that a sort of "tutorial doctest" could be run that created the
>    app the way the tutorial describes, and sees if it really runs and
>    returns the output the tutorial claims.

Do you know zope.testbrowser? What you describe sounds a lot like that. 
My book describes it.

>  - I was not sure, when writing, when to say "Grok" and when to say
>    "Zope".  There are several possible schemes we could adopt; I am
>    sure that I have not been consistent with any of them. :-)

It's a tough call. In general, I'd like us to say "Zope" when we're 
talking about a feature that we inherit from the Zope libraries (object 
persistence, object publishing, etc.) and "Grok" when we're talking 
about how this feature is applied and used in Grok. That's just one 
man's opinion, though.


-- 
http://worldcookery.com -- Professional Zope documentation and training