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

[grokomobil]

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.