Am 28.06.2010, 23:30 Uhr, schrieb Shane Hathaway <>:

> Matthias,
> You are conflating two conversations, and as a result you are reacting  
> to the non-stated suggestion that the packaging system provides  
> sufficient stability information to consumers.

I've experienced the packaging system is not useful to me without meta  
information like stability, widespread use, interoperability etc.. Yet  
people keep telling me "people can use your code if you package it". This  
is highly contradictory to me.

> 1) Yes, there is a lack of ZODB documentation.  Please feel free to  
> contribute by writing documentation, especially for the upcoming book.  
> However, keep in mind that there is no need to throw out packaging in  
> order to document ZODB and third party functionality.  Other people rely  
> heavily on packaging and have much more success with it than you  
> apparently do.

I do not want to focus on the technically broken packages. There are  
enough which work. Packaging as a means to make code downloadable and  
installable works.

The problem about documentation and packaging is this: I want to build an  
app. I go to I don't find lots of information how to query or  
index my database. If I was the casual observer, I'd leave the site right  
now and never come back. I'm not interested in the raw core skeleton of a  
database. Losing a user = losing a possible future contributor = losing a  
possible future customer (for those people who sell services around  

Ideally it goes like this: I want to build an app. I go to I get  
to know zodb has built in tools for most of the problems I'm likely to  
face. Great. Let's hit the download button. After installation I want to  
see/test a few of those features together. Then I read up on them in  
detail. Look at the wxPython package for a killer demo application which  
serves the purpose of pulling all the different widgets together for an  
end-user. I do not have to google all over the place to find a decent  
calendar or list widget.

So we could now go and collect a list of good packages and publish it. We  
could even write a tutorial which shows a use case involving three or so  
of these packages. We can publish it in a book or on the zodb main page.  
We can write a demo showcase application involving indexing and querying  
packages. In a few months or a year this won't work anymore, because each  
of the three packages will have gone down its own way. The package  
maintainers won't care about fixing the tutorial or application, they are  
already over-burdened with the work of keeping documentation of the  
package itself up-to-date. In two years one of the packages will be  
superseded. Most developers completely forgot there is a tutorial showing  
how to put three good modules together. That's the way current ZODB  
documentation and packaging work in my view. The once very useful "bigger  
picture" information - these three are good packages, you can use them  
together like this - is lost again. This information is what made ZODB  
useful and attractive to me in the first place.
The lack of collaboration between the packages and core zodb destroyed  
useful documentation. Packages pull changes from core zodb, but they don't  
push anything back. With a standard library structure this cannot happen.  
I want to emphasize a standard library can pull already existing packages  
for a start! There can be tests which enforce the interoperability between  
packages for example. This way the zodb ecosytem remains useable as a  
whole. It cannot diverge to the point where individual packages get  
meaningless. The whole thing is more than the sum of its parts.

In this spirit I think packaging and documentation are conflated.  
Packaging does not have to be thrown out at all. But packaging has to be  
used in a way so the individual components create a whole to which I can  
assign semantic value. Semantics can then be documented. Right now it's  
all splittered from the perspective of an end-user.

> 2) You seem to be interested in contributing a spatial index.  Great,  
> that sounds interesting!  You don't have to create a package, but that  
> is the best thing to do to gain an audience.

I'm not interested in an audience for the package. I'm glad if the index  
works for me. I can write unit tests to verify this. I'm happy if it's  
useful to others and want to give something back to the community so new  
user don't have to face the same issues I've faced. As of right now it I  
can't contribute in a way which would spare a new user the same issues.  
And I have a hard time believing I am the only one who's facing them.  
Other bigger python frameworks like twisted or wxPython never made me feel  
this way.

I'm interested in creating a zodb universe which is useable as a whole  
right from the start and where I don't have to find and pickup small  
pieces to glue them together in tedious work.


P.S.: This will be my last lengthy mail about this topic. I'll rather  
spend time writing blog entries for the docs project.
For more information about ZODB, see the ZODB Wiki:

ZODB-Dev mailing list  -

Reply via email to