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

Steve Schmechel steveschmechel at yahoo.com
Tue Sep 8 15:12:05 EDT 2009


It is published on the Grok site under Documentation --> Example Applications.  The link was at the end of my (overly long) post, but
here it is again:

http://grok.zope.org/documentation/tutorial/musical-performance-organizer-part-1

Hope it helps.  Let me know what you think and how it could be improved.

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, 1:54 PM
> 
> 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.
> 
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> https://mail.zope.org/mailman/listinfo/grok-dev
> 


      


More information about the Grok-dev mailing list