[Grok-dev] "Transient Objects" tutorial
Brandon Craig Rhodes
brandon at rhodesmill.org
Sun Sep 16 22:35:46 EDT 2007
I have submitted my first tutorial for consideration for the web site!
Thanks for everyone who helped me learn enough to write it. :-) Its
name is "transient-objects.txt" and it lives in the "minitutorials"
directory alongside the other submissions. Some notes:
- It uses many Unicode characters, and will probably cause your
grok2html to explode, so I have not presumed to add it to the
official "doc/grok2html.py" until we figure out how to make Unicode
possible in our documentation.
- 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:
On what kind of schedule do these sorts of fixes turn up in the
code which the average tutorial reader gets when they run
- The tutorial needs to link to a generic how-to-run-grokproject-and-
- 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!
- 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?
- 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.
- 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.
- 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. :-)
Brandon Craig Rhodes brandon at rhodesmill.org http://rhodesmill.org/brandon
More information about the Grok-dev