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

[Sebastian Ware]

True about grok-doc but since our focus is on maintenance, it only  
partly helps him in the short term.

Mvh Sebastian

On 2 sep 2009, at 20.47, Tim Cook wrote:

> 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 *
> ***************************************************************