[Zope] Zope Documentation

[Jim Penny]

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