[Grok-dev] The Grok Learning Curve

[Luciano Ramalho]

Basically I agree with everything you said, Sebastian. I just want to
add some ideas.

Most of the problems you mention have a common origin. Any community
of developers around a framework is made of two sets of programmers:
the framework developers and the framework clients. During most of the
history of Zope 3, the two sets overlapped almost completely, so the
docs, tools and practices of the community were dictated by the needs
of the framework developers.

Right now, in 2007, the set of framework clients is starting to grow
much faster than the set of framework developers, which is very good
for for Zope 3. Two major developments have spurred that growth: Five,
which allows Plone to leverage Zope 3, and Grok, which provides a much
easier path to pure Zope 3 apps. (It's interesting to note that both
Grok and Five began with Martijn Faassen. Martijn, you rock!)

So the docs, tools and practices of Zope 3 need to better accommodate
the needs of the framework clients, if the framework developers want
it to become more relevant to the world at large.

On 8/16/07, Sebastian Ware <sebastian at urbantalk.se> wrote:
> For me, learning Grok is like taking a trek in a rain forrest.
> Fortunately there are a lot of natives around and they are friendly
> and happy to share their knowledge. However, there is very little in
> terms of maps or even simple grafitti around. At least as far as I
> can tell. I have heard some references to sandboxes etc. but they
> might as well be hidden in caves, because it isn't all that
> accesible. All I see is trees...

That's a wonderful metaphor, Sebastian! In a forest, there are no
paths. Actually there are, but only the natives recognize them. To the
outsider, it's like: any path is possible, but you have to hack your
way whichever direction you go.

The Zen of Python says "There should be one-- and preferably only one
--obvious way to do it." But the very smart people who developed Zope
3 where traumatized by the monolithic Zope 2 so they designed a new
framework that almost *never* tells you how you should be doing
something: there are always many paths to chose from.

One example of the above is user authentication and user management:
everything is pluggable, there are many ways to do it, but how about
the one obvious way to do it? How exactly does one setup a PAU
programatically (Phillikon's book shows how to it in the ZMI)? And
then hows does one hook it up to a PrincipalFolder to store users in
the ZODB? Instead, all we get (from a Grok point of view) is the
principal registry in ZCML. I'm working on implementing a PAU with a
ZODB principal source in Kirbi, so we'll soon have an example but I am
not there yet. Has anyone already done something similar in a grok
app? Can we see the code?

> I had a similair experiece when learning Zope 2. Then I found DocTab
> extension and zopelabs.com and it changed everything to the better.
> Still, Zope was obfuscated by the abundance of documentation on the
> Zope website, most of which was outdated or incomplete.

I think there are a couple of reasons why the docs in the Zope website
don't get a lot of attention. The main one is the existence of the
apidoc tool, which sounds like a good idea (you get documentation for
your own particular Zope 3 installation, no more and no less). But the
main documentation for a framework *must be* published on the web for
everyone to see (try googling for Zope 3 api documentation) and, most
important, must be on the web so that people can share comments,
examples and advice about it (take a look at the PHP API docs to see
what I mean).

Ironically, having a public, canonical source for the API
documentation is getting *harder* with the trend in splitting Zope 3
into many independent packages. So perhaps it will be the task of the
Grok community to assemble a useful collection of packages and publish
their docs in a coherent public site.

> -If we get the class/object browser working well, a lot is won
> (browsing the Zope 3 source code in the file system can be rather
> confusing)

Yes, and then we set that up on a public web site, with ways to add
comments. That's been a proposed task for the Neanderthal sprint that
Uli, Aroldo and I have been discussing.

> -I also believe that we would gain a lot if we could get people like
> myself setup so they can debug their projects more efficiently
> (someone mention post mortem debugging, currently I am still stuck in
> trial and error!)

+1

> -I also believe (contrary to a comment in a post on this mailing
> list) that it is quite useful to use recipes that "just work"
> eventhough one at the time doesn't understand how (that's how most
> people learn to talk and read -- learn by example)

+1

> -Also, there is more and more docs and stuff on Zope 3 (I have
> Philipps book right beside me) but I am not 100% confident with how
> to "translate" it into the Grok universe (I do the trial and error...)

+1

> So, I would suggest focusing/furthering the efforts along these four
> paths:
>
> 1 -- Refine the class/object browser
> 2 -- Document how one sets up a usable debugging environment
> 3 -- Add more recipes (currently called Howto's)
>
> ...and less important but still very useful if one owns Philipps book...
>
> 4 -- Document how one translates pure Zope 3 knowledge to Grok

5 - Build a public API documentation site where people can share their

> Everybody can write a recipe, I mean a recipe showing how to register
> and use a utility is really useful to a newbie. A recipe showing how
> to create and extend users...

I am working on Kirbi which will demonstrate dealing both of these
(utilities, users). I'm just not there yet.

Yes!!!!

Regards,

Luciano