[Grok-dev] Re: an 'about grok' document

Wed Mar 21 16:14:38 EDT 2007

Martijn Faassen wrote:
> I've tried to sketch out a document that tries to explain to beginners 
> why Grok's important and should be considered for your web application. 
> I basically fall back on a lot of stuff on why Zope 3 is great, and how 
> Grok is based on it, but tries to make it more easy to get into.
> 
> http://svn.zope.org/grok/trunk/doc/about_grok.txt
> 
> Please give feedback.

The text is great. It says everything it needs to say. I do share with 
others on this list a concern that Zope 3 is mentioned too often. 
Somebody coming from a non-Zope background might be confused by all this 
mentioning of Zope 3.

Another concern I have is the first section of the document. It mentions 
a lot of adjectives (fun, agile, extensible, etc.) in relation to Grok 
and then gives Zope 3 as the reason why that is so. I think we can do 
better in explaining *why* Grok is that way.

Attached you'll find a modified version of the document that tries to 
alleviate both problems, especially the latter one. I only changed the 
first section (I think the others are ok) and I incorporated as much of 
the original text in the new version. Let me know what you think.

> Eventually I want to put text like this on grok.zope.org.

Yes, it should be in an "About" tab between Home and Tutorial.

-- 
http://worldcookery.com -- Professional Zope documentation and training
-------------- next part --------------
Grok: now even cavemen can use Zope 3
======================================

Grok: Experience, Expertise, Extensibility
------------------------------------------

Grok is a web application framework for Python developers. It is aimed
at both beginners and very experienced web developers. Now you will
have likely heard about many different web frameworks for Python. We
will explain why you should consider Grok:

Grok is agile
.............

Thanks to grokproject_, you'll be able to create your first web app
with Grok in no time. Only one command will set you up with a
completely functional development sandbox and a small Grok application
that you can start customizing. When doing so, you won't have to edit
cryptic configuration files -- simply start by adding Python code or
HTML templates.

.. _grokproject: http://cheeseshop.python.org/pypi/grokproject

Grok is fun
...........

Grok tries to give you instant satisfaction during development. If you
want to start with the UI of your web application, Grok won't be in
your way. If you don't want to worry about security until later, Grok
will worry about it for you until you decide to worry about it
yourself.

Grok offers a very wide range of features
.........................................

Grok stands on a giant's shoulder. That giant is Zope 3. Through Zope
3, it offers a *lot* of building blocks for your web application. No
matter whether you need transparent object persistence, LDAP
authentication or sessioning -- Grok has it.

Grok is extensible
..................

Successful web applications aren't built for a day - such an
application will need to be maintained, extended, evolved, over a
period of many years. Zope developers really know this. Grok, through
Zope 3, offers a basic architecture that enables your application to
grow over time.

Grok is grounded in a deep experience with web development
..........................................................

Grok, through Zope 3, is informed by a *lot* of hard-earned
wisdom. Zope 3 is a powerful and flexible web application framework
for Python that has been under continuous development since 2001.
Zope 3's design in turn is based on experience with the Zope 2
platform, which has been under continuous development (starting Bobo,
Principia and then Zope 1) since 1997. The Zope community is supported
by an independent foundation, the Zope Foundation.

Zope 3 features a large amount of API documentation and aims for
reliability. It has a very large automatic test coverage (many
thousands of tests). It has a large set of core features, and sports
an enormous range of plug-in components.

Grok: Zope 3 for cavemen
------------------------

Zope 3, unfortunately, also has some problems: its power also raises
the entry barrier for developers to get up to speed with it. Even
after you've learned it, its emphasis on explicit configuration and
specification of interfaces can slow down development.

Grok aims to remedy these problems. Grok aims to make Zope 3 easier to
learn, and more agile to work with, while retaining the power of Zope
3.

Grok appeals to the caveman or woman in all of us. Cavemen, like us
programmers, want powerful and flexible tools. Cavemen are great at
tools after all; they invented the whole concept of them. But cavemen,
and we, also want our tools to be simple and effective.

Cavemen want tools like clubs: a club is powerful, flexible (you can
bash in anything, mash potatoes too) and also simple and
effective. Zope 3 is already powerful and flexible. Grok aims to make
it simpler and more effective, for beginners and experienced
developers alike. Grok: now even cavemen can use Zope 3.

Grok from the Zope 3 perspective
--------------------------------

Zope 3 allows you to combine different components in an explicit,
flexible way. You can hook up a view to a model, an event handler to
an event, and a new API to an existing object. The process of doing
this is called *configuration*. In a technical sense, Grok can be
understood as an alternate configuration mechanism for Zope 3.

Zope 3 without Grok uses ZCML for hooking up objects together. ZCML is
an XML-based configuration language. ZCML statements are stored in
their own file, next to the code. While using ZCML has the benefit of
being explicit and flexible, it can also make code harder to read as
there are more files to consult in order to understand what is going
on.

Grok does away with ZCML. Instead it analyzes your Python code for the
use of certain special base classes and directives, and then "groks"
it. This grokking process results in the same configuration as it
would have if you used the equivalent ZCML. We believe that having all
configuration along with your Python code makes the code easier to
follow and more fun to develop.

Grok has been designed so that if you organize your code in a certain
way, you can even leave out most of the explicit directives in your
Python code. This makes code written for Grok look clean and
uniform. You still have all the power of explicit configuration
available should you need it, however.

During the development of Grok we have taken a careful look at common
patterns in Zope 3 code and configuration. Grok aims to make these
patterns more easy to use and succinct.