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

Tue Sep 8 14:03:14 EDT 2009

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
> 