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

[Martijn Faassen]

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.  

Wow, cool!

[snip]
> 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.

I really need to find the time to read this and give feedback. You 
should definitely remind people regularly that it's there, and solicit 
feedback on this mailing list.

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

I think this is a good point. I think however that putting too many 
demands on anyone who wants to write some tutorial text might deter some 
good texts being written. But we could institute such a policy for the 
*official* Grok documentation that we maintain in the 'doc' directory in 
SVN. In fact the tutorial there does have working buildouts for all the 
steps in the doc/groktuts subdirectory (I recently updated them all so 
they work independently without requiring another buildout.cfg, which 
they used to do).

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

Agreed!

> 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 am still convinced they're not at all at odds with one another. It's 
"merely" a matter of good documentation to bridge this gap. 
Unfortunately producing this documentation is an intensive effort. 
(actually it's not only that. we've been working actively to try to make 
a future Grok pull in less Zope Toolkit code than it does now)

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

The heart of the difficulty is also the heart of the project. It's not 
an easy challenge, but I think it's a challenge that makes it worthwhile 
to rise up to it.

I think you make a good point about planning in connection not only with 
features and such, but also in connection with documentation and 
learnability.

Thank you very much for your extensive feedback. Please do keep talking!

Regards,

Martijn