[Grok-dev] Re: Parallel sprint in Brasil

[Martijn Faassen]

Luciano Ramalho wrote:
> Dirceu Tiegs and I are organizing a Brasilian Grok-sprint to happen in
> parallel with the one in Vilnius. Our plan is to work on the Tutorial,
> after getting a green light from Martijn Faassen.
> 
> What we want do to:
> - follow Marijn's plan in doc/tutorial_outline.txt as far as we can
> - include a lot of information already in the design docs which are
> not science-fiction anymore, except for spelling differences in many
> cases
> - show Groks autoform funcionality early on, and leave hand-coding of
> forms to more advanced sections about custom forms

I'd like very much to hear more about your plans here, as I don't agree 
with this approach. I showed custom, HTML-based forms first, because:

* people familiar with HTML will understand what's going on without 
having to learn a lot of new concepts, such as interfaces, schemas, 
formlib, etc.

* it is a very good opportunity to show how information flows through 
the system.

* sticking with hand-written forms doesn't complicate the tutorial very 
much.

In general, you need to be very careful in the tutorial not to introduce 
too many concepts at once. I tried to be careful to only introduce a few 
new things per section, and currently interfaces and thus schema aren't 
even covered yet.

I think that the bits about custom forms will help people gain 
understanding of writing all kinds of web applications, including a 
better understanding of what goes on with automatic forms, which 
inevitably they will have to adjust. It helps construct a gradual 
learning curve. I'm worried that if you introduce formlib-based forms 
early, you'll break the learning curve.

The tutorial already has a sidebar to point out clearly that you can 
automate this, and point the user in the right direction, while not 
breaking the flow of things. Perhaps this can be expanded upon somehow.

I can see from a marketing point of view you'd like to show automatic 
forms earlier on, to show off the power of Grok. The tutorial should 
primarily be a teaching instrument though. A more modular tutorial could 
help with marketing anyway - you could allow people to jump in at 
automatic forms and provide various 'tours'.

> - make the tutorial more modular, perhaps splitting in several pages,
> to make it easier to integrate contribs like Sebastian Ware's recent
> searching tutorial

+1 to all the other efforts.

Note that you should definitely set up the tutorial sample applications 
under groktut. If you are changing the tutorial or introduce new sample 
applications, please expand from there. Read doc/groktut/INSTALL.txt for 
information for how to make the installation go very quickly using buildout.

Regards,

Martijn