[Zope3-dev] Why I posted about Zope3.org (the outsider's thoughtsthat got me thinking)

[Mats Nordgren]

-----Original Message-----
From: zope3-dev-bounces+mats=ronin-group.org at zope.org
[mailto:zope3-dev-bounces+mats=ronin-group.org at zope.org] On Behalf Of Jeff
Shell
Sent: Tuesday, October 11, 2005 11:27 AM
To: Stephan Richter
Cc: zope3-dev at zope.org
Subject: Re: [Zope3-dev] Why I posted about Zope3.org (the outsider's
thoughtsthat got me thinking)

On 10/11/05, Stephan Richter <srichter at cosmos.phy.tufts.edu> wrote:
> On Tuesday 11 October 2005 13:24, Jeff Shell wrote:
> > I'd really like to give Zope 3 a try, and I keep trying to. The docs
> > are just nauseating. They might look good or fine to someone who's
> > used Zope for years, but to someone new they're horrid. As I
> > mentioned, the site is laid out horribly for someone who wants to
> > learn Zope 3. Why is the left bar saturated with links when I just
> > want Zope 3?
> >
> > It's incredibly frustrating and disappointing to hear about all the
> > cool stuff you can do in Zope 3, and not see anywhere that shows it
> > actually being done with descriptions on how it works, etc. Where are
> > the examples? Where are the recipies to "do cool thing X"?
> >
> > The developers I see talk about Zope are all in companies that use
> > it, that have teams that use it, that have tons of actual knowledge
> > that doesn't exist on the website. I really really want to give Zope
> > 3 a spin, I have a few fairly complex projects I'd like to try out
> > with it. How do I get started?
>
> I would say, buy the books. It is too hard to keep documentation up to
date,
> if you do not get paid. The alternative are doctests of course, which we
have
> available as mentioned in my previous mail. Again, I think it is a lack of
> manpower, my own included. I would love to update the Web site to the
version
> of my book that has actually been printed, but I just do not have time.
All
> it needs is someone to merge the stupid DOC files to the TeX master
documents
> and it would be online. Note that I already put them in a zope.org-based
> repo, so anyone can work on that task.

That was my response to him. But for people evaluating Zope 3, or just
starting out and not knowing whether it's a worthwhile technology to
continue with, buying a book is probably a non-starter. Some good
"quick starts" and recipes would help there. I don't think that the
type of documentation that is in a book should be on the web site and
maintained constantly. It's too big and too hard, a fact I'm sure
you're aware of.

The API Doc tool, the books, are all useful things to have once you've
really committed to a project. But getting people that far is where
zope3.org or maybe zope3rocks.com or something - anything! - would be
useful. Instead of trying to update reams of documentation with new
features in Zope 3.2, one could post a document like "Zope 3.2 -
Introducing zope.formlib" or "Zope 3.2 - deprecated functions"

Because, for example, I see the warning about using 'getView - use
getMultiAdapter instead', but there's no explanation of how a
getView(...) call should be translated into a getMultiAdapter call..
One can figure it out, but it's a couple of lines that could be in a
document that many of us here can write.. I just don't want it lost in
the desert sands of the wiki. I can find proposals about simplifying
the component architecture, but there's no final document about what
that simplification really produced and how it affects me. The
deprecation machinery is great at telling me about these things (again
- I think it's a great feature), but oh man - I think any major
architecture like Zope 3 that gets *simpler* in a new version is
something to sing about.

For the record, Philipp's book should be here on the 13th and I started out
with printing the tutorial chapters of Stephan's book.  It is starting to
get a bit worn, so just perhaps that will be the next book I buy.

My point is not to have book length tutorials, but specific
tutorials/howtos/recipes.  Perhaps with vocabularies specifying tested
version.  I sometimes find myself confused on how to translate from doctest
to an implementation within Zope.  
So for example, I want to find out how to use Catalogs, there would be a
howto that would build a simple catalog with zcml configuration and how to
get it to index and tick inside of Zope, a howto on how to program and
configure a user/authentication system, and make it tick inside of Zope.
Very topic specific.  Maybe I'm asking for a lot.  Maybe I a haven't reached
ZopeZen.  Maybe I haven't taken the initiative to ask for help.  Just seems
stuff like this is what would encourage and draw people to Zope.  Anyhow,
just my 2 cents.

I know manpower is limited.  I have offered to help, but I am not sure where
I can fit in the best.  Perhaps if I occasionally posted a question/topic on
the list, I could compile and test the examples/suggestions given and add it
to the wiki or a simple doc. Maybe that would be of help.

Mats