On Fri, Aug 09, 2002 at 11:01:10AM +0200, Breuer, Yvon wrote:
Hi *,
I *really* think it's time to make a strong effort to get a better Zope documentation. According to me many people agree that something needs to be done. But I also think that it's not very clear *how* it should be done the best way...
Trevor Toenjes has made a very good 'beginning'! (Although beginning probably isn't the best term for it.) Maybe it's sufficient to extend his work with some ideas from Patrick Price. I'd like to ask you *all* to (re)think about *what* needs to be documented and *how*.
We need two types of users for this discussion: 1. experienced users: Together (!) they know what's good about Zope, they know the best (or 'preferred' products, they know what should be the best way to *learn* and how to *use* Zope, they know which questions are asked many time, etc. etc. 2. unexperienced users: Together (!) they know what is missing, what is unclear, they still have a fresh look at Zope and probably wonder why something is done 'this way' and not 'the other way'.
Don't forget that the early users have grown into Zope and it's continuing expansion (as in users, as in complexity, as in possibilities, as in ...). It looks like newcomers can't see the forest anymore because of all those trees standing in the way... (It's a freely translated Dutch saying.)
Last example (see other examples below!!!): I'm working myself through the ZopeBook at the moment. It's *really* helpfull and I learn constantly, but: At first I read about DTML, about how good it is and it's possibilities. Eveything ok. After that I started to read about Page Templates. Again even more (and nice) possibilities, but it also said somewhere that it's better to use Page Templates instead of DTML... So, why learn DTML first? A bit further it's even said that it is even better to do everything with Python... So, why not forget all about Page Tamplates and continue with Python? Isn't that strange? Isn't it confusing? When do use what? And Why?
No, a bit, when it works well, because it works well, resp. The DTML/ZPT divide is the most controversial. But it has much to do with history. In the days of yore, you could extend zope by external methods, python products, and z-classes. That was it. (Script (python) is relatively recent.) DTML is very much an exercise in what a "little language" for page design would look like to someone who had a lot of experience in classical imperative programming languages. Behold: alteration, iteration, assignment, all in forms that would look pretty typical to any programmer, if only the <dtml- prefix were dropped. Experience has shown that it was something of a trap. There was a tendency to push too much into DTML, mixing logic (which after all, is what alternation is all about), and presentation. This was, in the mind of its designer, leading to a really awful situation, where logic and presentation were being too intermixed, to the detriment of both. The presentation could not be read because of the logic, and the logic was really slow because it was being interpreted, by another interpreter. ZPT is another exercise in a "little language", based on XML rather than imperative programming languages. I must admit that I did not understand it for far too long a time, and still have not given it all the attention it deserves. But, as I have used it more, I want to use DTML less. Does that mean DTML is obsolete? No, not really, there are times when it is easier to mix a bit of logic in than to create another method. And some things are, in fact, easier to think of in terms of imperative programming languages than in terms of textual substitutions. Well, as to python, it is getting out of the "little language" paradigm (although compared to PL/1, or C++, it is still very much a small language). The ability to easily escape to python is one the Zope's greatest strengths. The pleasure of not having to deal with databases in python is also a great strength! Python has one of the best string handling libraries known, but it is not a templating system.
Which products exist? What do they do? How do you know? Is it a good product (according to the community)? Is there a newer/better product?
Please, take it up!
Best regards,
Yvon Breuer
I have been using zope, as a developer, for quite a while now. You newbies have no idea how much easier it is! Back in my day, you had to walk through six feet of snow, against a raging wind, uphill, both ways! Look, there are three problems, all interrelated: 1) Documentation seriously lags development. This is typical of software in general, but community developed software seems even worse. I see the Zope book as a good 2.2 book, with add-ins to update it to 2.4+. It is unfortunate, but natural, that the ZPT documentation was done as an add-on. Ideally, ZPT would be presented before DTML. 2) The documentation has historically been extremely focused on "how to", not "when to" or "why to". Again, this is fairly natural. First, no one wants to insult someone else by "teaching his grandmother how to suck eggs". Also, much of zope is somewhat novel, and it is taking a bit of time for "best practices" to develop. I think that you will see the next version of the Zope Book offering a bit more advice about "why to". 3) Third party products - there is little consensus on which products are, in fact, good. Every product developer tends to think that his is best! (And in fact, it usually is, for _his_ problems.) For example, I still use LocalFS, despite looking at several alternatives. The alternatives simply do not do what I need! It would be nice for Zope to have a developer/maintainer registry, like Debian's, with a way to mark a package orphaned, and a way to adopt a package, but I can certainly understand whay Zope Corp has not doen this, to date. (It adds a barrier to entry, it is a bureaucratic solution, it is a small constant irritant to everyon involved, at best) Jim Penny Jim Penny