[Zope-dev] Zope 3.4.0 Released!

[Shane Hathaway]

Stephan Richter wrote:
> It is finally here! Thanks goes to everyone who involved!
> 
> January 29, 2009 - The Zope 3 development team announces the Zope 3.4.0 
> release.

Excellent!

I have to say, though, that the download process is quite confusing. 
Let's say I'm a Pythonista who wants to try out Zope 3.  Google sends me 
here:

http://download.zope.org/zope3.4/

After the release overview, the document tells me Zope is now 
distributed as eggs.  I'm familiar with eggs and I like them.

Then it talks about the KGS and my buildout.  It tells me how to modify 
my buildout configuration.  Wait, what's a buildout and how do I 
configure it?  Hmm, none of the links about the KGS tell me much about 
this buildout thing.  I can already tell it's gonna be hard to learn 
about Zope...

Well, I'll skip over the KGS stuff and see what I can figure out anyway. 
  Ok, I can follow the easy_install directions.  I'm really savvy and 
I'll even use virtualenv to do it, even though the document doesn't 
mention that.  I already have the habit of using virtualenv whenever I 
use easy_install.

So, following the directions, I create a project called HelloWorld.  I 
try to fire it up.  Uh-oh...

zope.configuration.config.ConfigurationExecutionError: <class 
'zope.configuration.exceptions.ConfigurationError'>: Help Topic 
definition [...]/transaction-1.0a1-py2.5.egg/transaction/README.txt does 
not exist

So it breaks before even starting the server.  This is really trying my 
patience, but I study a lot of web pages and discuss the problem with 
other developers over a few days.  Following a friend's recommendation, 
I add the following two lines to the [buildout] section of buildout.cfg 
generated by zopeproject:

   extends = http://download.zope.org/zope3.4/3.4.0/versions.cfg
   versions = versions

After running bin/buildout again, the server finally starts!  Of course, 
what I see when the server starts is opaque and uninviting, but I'll 
leave that for another discussion. :-)

So, my question is: what should the download page *really* say? 
Consider that existing developers of Zope 3 don't actually need this 
page at all since they already use zc.buildout.  This page's audience, 
then, is people who know little about zc.buildout, let alone the KGS. 
Newbies need straightforward directions to follow.

Shane