[Grok-dev] Grok Documentation

[Steve Schmechel]

03/01/2009, 03/28/2009, 04/22/2009

These are the last three "change dates" of Grok Documentation on the website.

The documentation "push" seems to have faded away.  While there is some good documentation on the site, it is hard to believe that it is complete.

Sprinkling the documentation in various README's and in mailing list threads, hasn't attracted new developers to Zope in the past.

For a new project that hasn't reached version 1.0 yet, "one change per month" either means that there are few changes going on (I know that is not the case), or that Grok does not really want to attract a wider audience.

I can see how Grok can make a professional Zope developer's life much easier.  The story for introducing someone to Python-based web development using Grok, is not as clear.

This is a shame because it is very impressive how much you can do with Grok with just a few lines of code.  (Try to create even a simple web site in ASP.NET without the code generation from Visual Studio wizards and designer, and you will see my point.)

The problem is that when you go beyond the simple tutorial and want to get something meaningful done, the next "simple line of code" becomes harder and harder to find.

Fortunately, there are many helpful and experienced developers on the mailing list that are willing to help.  But when you need the help of others most of the time, it does not build one's self-confidence that you are actually "learning" how to use a tool in a way that you will be confident when you are responsible for the results.

Good documentation is the key to building that confidence in others, so they can go beyond learning and tinkering and become the next generation of professional Grok/Zope developers.

Is documentation still a priority for Grok?

(As I was writing this and eating breakfast, I see Tim Cook just volunteered to help with documentation.  Amazing!  Looks like the documentation topic is back on the table.)