[Grok-dev] Re: updating the tutorial

[Philipp von Weitershausen]

Martijn Faassen wrote:
> class Index(grok.View):
>     pass # see app_templates/index.pt

Ooops, not documenting that was an oversight.

> There's also an ``app_templates`` directory that we ignore in the first 
> tutorial section now.
> 
> That's not a good start for anyone following the tutorial: the code they 
> see when following the instructions isn't the same as what the tutorial 
> says it should be.
> 
> So, the lesson for everybody is that when you update the tutorial, 
> *also* update doc/groktut. I'll update it for you this one time. :)

Thanks. :)

> P.S. I realize updating the tutorial is another step and rather a pain. 

I'll add that it is a *major* pain right now, the way it is set up with 
lots of independent buildouts that have to be run each time (which takes 
ages and doesn't exactly create a flat directory structure for us).

Another painful thing was that a separate grok eggs gets downloaded 
instead of the development egg in src/grok being used. I tried to fix 
that but the only way that really worked for me was to change each 
section's buildout.cfg like so::

    [buildout]
   -develop = .
   +develop = . ../../..
    extends = ../buildout_tut.cfg

Of course, I didn't change every file since I wonder if there's be a 
better way. What do the buildout masters say?

> It's essential to the success of this project however. I've tried to 
> make setting up the examples as fast as possible too: read 
> doc/groktut/INSTALL.txt

Thank you for taking the time to write this down. I'm inclined to argue 
that we shouldn't make people update the tutorial on a mandatory basis. 
People will be sloppy (just look at me :)) and people will not always 
get it right. Also, I plan to do some work on the reference soon. If we 
made people update that at the same time, we'll increase the burden even 
further (not to mention we already make people write doctests, which is 
a good thing but it's a burden).

I realize the importance of the documentation, but I'd hate to see the 
bar for Grok development raised too much.


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