[Grok-dev] Re: updating the tutorial

[Martijn Faassen]

Hey,

On 3/20/07, Philipp von Weitershausen <philipp at weitershausen.de> wrote:
> Martijn Faassen wrote:
[snip]
> > 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).

No no no. Follow the instructions in the INSTALL.txt. ../buildout -N
should only take
a very very brief time. I spent a lot of time making it so. All eggs should be
shared between each buildout. bootstrap needs to run only once. A
single Zope 3 setup is shared between all buildouts. It's basically
just setting up a Zope 3 instance, and on my machine that takes less
than a second.

> Another painful thing was that a separate grok eggs gets downloaded
> instead of the development egg in src/grok being used.

That would be nicer.

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

Hm, we should ask Jim.

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

People should at the very least mark changes that have an effect on
the tutorial. What would be the right place for this? We should
starting maintaining a CHANGES.txt file anyhow, perhaps that can be
used for this.

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

It's a difficult balance to make. Just realize that running an
individual buildout of a tutorial is extremely fast (after the first
time).

Regards.

Martijn