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

grokomobil battlefox at gmail.com
Tue Sep 8 14:54:17 EDT 2009 

That is exactly what i think about grok aswell.
I guess that this 40 page tutorial you made is far better than any other
tutorial made by grok-experts. Simply because I'm conviced that a beginner
really knows where beginners normally get stuck while learning grok. I hope
you can publish your tutorial somewhere on the net cause a lot of beginners
might benefit from it. Maybe others (maybe me too) will follow your example
and write real beginner tutorials aswell.


Steve Schmechel wrote:
> 
> I also struggled with the tutorial being too simple and the how-to's
> being disconnected and difficult to follow without Zope experience.  
> 
> So, I started writing a much larger tutorial from the perspective of a
> beginner (which I am) trying to build a working application using Grok.
> It covers a broad range of topics (covered more specifically in other
> tutorials, how-to's, and component documentation) in a practical manner,
> including: project setup, file structure, using buildout, unit testing,
> functional testing.  
> 
> It takes an iterative approach and includes generously complete code
> listings and screen shots (two things I found very lacking in other
> documentation).  It uses grok.form with auto-forms and transitions to
> custom page templates as the requirements dictate.  The resulting
> project and code may not be the most elegant (I'm fairly new to Python
> also), but it allows one to "get your hands dirty" manipulating the code
> and seeing the results. [1]
> 
> The main drawback of this approach becomes the size of the tutorial
> itself.  Part one is about 40 printed pages.  I am finding it hard to
> get anyone to take the time to read it and offer feedback, much less
> help me extend it and make it better.  I'm not sure parts 2 and 3 will
> ever be completed as the time needed to write them is significant and,
> if no one is going to use it, I will find other ways to give back to the
> Grok community.
> 
> Maybe another approach is to make all the existing pieces of
> documentation more cohesive and uniform.  They could all start from a
> fresh grokproject install and always include *all* the additional code
> and template work necessary to make them work.  Even if the end result
> isn't useful by itself, having it work and being able see a sample of
> the functionality when you are done is encouraging to the beginner.
> 
> It is easier to take something that works and modify it to your needs
> than to always question if it was your change that broke it or some
> missing piece of information that doomed it from the start.  The second
> scenario is very discouraging.
> 
> Some personal observations about Grok (for what they are worth):
> 
> I get the feeling that Grok, as it is today, must be a great
> productivity booster for those who already know a good deal about Zope.
> 
> For the beginner, however, it feels like you move in quick bursts between
> problems that stall you completely.  I find myself often being stuck and
> following all the "seemingly obvious" ways to continue, just do not lead
> anywhere.  So I search around for documentation, which turns up sparse,
> related Zope3 documentation and code that is often complicated and,
> after fighting to make it work, turns out to be outdated or irrelevant.  
> 
> Eventually, I ask on the grok-dev list and someone points out the way to
> do what I want to do and I make great progress again, until the next
> show-stopper.  (A testament to patient and helpful Grok developer
> community.)
> 
> While some of this is normal and "to be expected", it seems to be all to
> common.  I haven't really developed the confidence in my skills to
> commit to doing a paid project with Grok yet.  I feel like I should
> probably go through PvW's book again and commit to mastering Zope3, then
> I could use Grok to make my life easier.  (I also played around with
> Repoze.BFG, which takes a more low-level approach to taming Zope.  While
> a Zope master could probably move faster with Grok, for a beginner
> small, repetitious steps are often easier to make progress with.)
> 
> Maybe these two concepts are just at odds with one another.  Can someone
> who doesn't understand the underpinnings of Grok and the Zope CA use it
> effectively, or is it like handing the keys to a Porsche to a teen; the
> eventual crash will be spectacular and require a team of professionals
> to dig them out?
> 
> I'm not trying to be philosophical, but maybe the heart of the
> difficultly stems from what Grok is trying to accomplish; make something
> powerful *and* simple to use.  Maybe dealing with this difficulty should
> be part of the development plan and as important as getting version 1.0
> out the door.  If not, maybe Grok should first be promoted as a working
> framework and productivity booster, and the time frame for it becoming
> "easier to learn" spelled out as a goal for a future version.
> 
>>From the Grok website:
> 
>  Some aspects of Grok development require more detailed knowledge of 
>  Zope 3 (such as authentication) but it is our goal to make Grok a more
>  approachable, easier to learn framework over time. If you find yourself
>  bonking when trying to accomplish something, please let us know where
>  you are struggling.
> 
> [1]
> http://grok.zope.org/documentation/tutorial/musical-performance-organizer-part-1
> 
> Steve
> 
> 
> --- On Tue, 9/8/09, grokomobil <battlefox at gmail.com> wrote:
> 
>> From: grokomobil <battlefox at gmail.com>
>> Subject: Re: [Grok-dev] Grok & the lack of good documentation
>> To: grok-dev at zope.org
>> Date: Tuesday, September 8, 2009, 10:09 AM
>> 
>> The main tutorial is indeed easy to understand. Probably
>> even a litle bit too
>> easy to give you enough knowledge that is needed to go on
>> yourself. The
>> problem, especially for important topics like widgets and
>> schemas is, that
>> you get no information about them here. You have to crawl
>> through the Zope
>> API to get at least an idea what default methods they have,
>> what default
>> widgets are etc.. At this point, you have already lost
>> beginners before they
>> even created their first grok.form
>> It's not possible to leave out everything that deals with
>> zope-stuff if you
>> want to explain a newbie how to use grok. Referencing to
>> the Zope API is no
>> excuse here cause there is no real explanation either. 
>> 
>> 
>> Martijn Faassen-2 wrote:
>> > 
>> > grokomobil wrote:
>> >> Back to topic:
>> >> 
>> >> I think a big problem with the recent
>> documentation is also the fact that
>> >> a
>> >> lot of Zope knowledge is required to work with
>> them. In many
>> >> documentations,
>> >> it seems like most of the authors explain how
>> things work in grok, but
>> >> when
>> >> there is zope specific code in it (like things
>> from the formlib) they try
>> >> to
>> >> avoid any explanation for it. The developers of
>> grok stated that you can
>> >> use
>> >> grok without knowledge of zope, it seems like this
>> is not 100% possible.
>> >> Or
>> >> at least, no one cares when he writes a tutorial
>> or how to for it.
>> > 
>> > I hope at least some of the tutorials were helpful to
>> you. I tried to 
>> > write the main tutorial and the developers notes with
>> the idea in my 
>> > mind people should be able to understand it without
>> previous knowledge.
>> > 
>> > It'd be nice if people would help write such documents
>> and integrate 
>> > them into the official documentation.
>> > 
>> > Regards,
>> > 
>> > Martijn
>> > 
>> > _______________________________________________
>> > Grok-dev mailing list
>> > Grok-dev at zope.org
>> > https://mail.zope.org/mailman/listinfo/grok-dev
>> > 
>> > 
>> 
>> -- 
>> View this message in context:
>> http://www.nabble.com/Grok---the-lack-of-good-documentation-tp25259107p25348077.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
> 
> 

-- 
View this message in context: http://www.nabble.com/Grok---the-lack-of-good-documentation-tp25259107p25352048.html
Sent from the Grok mailing list archive at Nabble.com.

More information about the Grok-dev mailing list