[Grok-dev] Grok & the lack of good documentation

[Sebastian Ware]

I agree with you that Grok in it's current state of documentation is  
not a framework for everybody. Currently it suits pioneers who don't  
mind examining code and setting break points to investigate what goes  
on under the hood.

That said those two methods of investigation and the mailing list has  
helped me a lot and I would certainly not claim to be a stellar  
developer.

I decided early on to invest in Komodo IDE to get a nice graphical  
debugger, and without it there is no way I would have come as far as I  
have with Grok. I mean, in the beginning there was no documentation at  
all...

I believe the situation is slowly improving, a book has been written  
which will be released with Grok 1.0. You might find it useful.

Just some reflections.

Mvh Sebastian

On 2 sep 2009, at 17.08, grokomobil wrote:

>
> Grok always claims himself as a powerful but easy framework. But if  
> you start
> as an apprentice (like me) to work with grok, you realise how weak the
> documentation around grok really is. Most of the tutorials seem to be
> written and reviewed by grok experts who have no feel for the needs  
> of a
> grok-beginner at all. Some things are even completely left out.
>
> A few examples:
>
> Topics that are to small or even left out in the grok documentation:
>
> - Detailed explanation how the basic widget-methods (__call__,
> __toFieldValue) work, and how to use them to write your own.
> - How does the setupWidget-method work and what can you do with it?
> - How to work with 'invariant'-Methods in interfaces (recent doc is  
> too
> short, code is buggy)
> - A better explanation of "How to authenticate with grok" (recent doc
> contains excuses that explanations are still missing, finally the  
> code is
> buggy)
> - How to make a good navigation for a grok-site
> - A better explanation of how to use  grok.form in combination with
> Pagetemplatefiles
> - A detailed description about the level-concept of grok (container,  
> model
> etc.) with figures, explanation of how to navigate through the levels:
> __parent__, __name__ or passing arguments: ?abc=0 to forms
> - Detailed info of how to make formfield-validation in grok.form and  
> how
> flash-messages work.
>
> the list of missing or weak documentation is endless...
>
> Another big problem is, that some tutorials contain a lot of code  
> but no
> real description about grok-specific commands like @grok.action or
> applydata.
>
>
> The potential of grok is great and it is probably easy to learn. But  
> to make
> it accessible to more people, a more detailed documentation should  
> have
> highest priority.
>
> EDIT:
> Another problem is the chaotic storage of the grok documentation.  
> There are
> several tutorials (for example 'about forms' which describe all more  
> or less
> the same topic) It would be better to have one good and complete  
> description
> than doozens of snippets to search through. Quality comes before  
> quantity
> ;-)
>
> -- 
> View this message in context: http://www.nabble.com/Grok---the-lack-of-good-documentation-tp25259107p25259107.html
> Sent from the Grok mailing list archive at Nabble.com.
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> https://mail.zope.org/mailman/listinfo/grok-dev