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

[Tim Cook]

I agree with you Sebastian; a good IDE is invaluable, especially for new
comers.

Of course you did miss the opportunity to mention the grok-doc project
that is underway.  :-)

https://mail.zope.org/pipermail/grok-doc/2009-July/000002.html

Maybe the OP will have a few minutes to help?  It is always new comers
that can find the flaws much easier.

Cheers,
Tim

On Wed, 2009-09-02 at 18:16 +0200, Sebastian Ware wrote:
> 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
> 
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> https://mail.zope.org/mailman/listinfo/grok-dev
-- 
Timothy Cook, MSc
Health Informatics Research & Development Services
LinkedIn Profile:http://www.linkedin.com/in/timothywaynecook 
Skype ID == timothy.cook 
***************************************************************
*You may get my Public GPG key from  popular keyservers or    *
*from this link http://timothywayne.cook.googlepages.com/home *
***************************************************************
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20090902/efe9b1fd/attachment.bin