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

[Marcel Klapschus]

grokomobil is now known as "Marcel Klapschus" ;-)


Marcel Klapschus 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-tp25259107p25437281.html
Sent from the Grok mailing list archive at Nabble.com.