[ZDP] Zope docs impressions

[Michel Pelletier]

> -----Original Message-----
> From: Tom Deprez [mailto:Tom.Deprez@uz.kuleuven.ac.be]
> Sent: Tuesday, May 11, 1999 7:38 AM
> To: zdp@zope.org
> Subject: Re: [ZDP] Zope docs impressions
> 
> I thought this was the outline of a book Michel was 
> writing... for publishing
> 

Well, yes.  Unfortunately there aren't enough 'Mike' Pelletiers going
around to ever get it done.  Actually developing parts of Zope is taking
up too much of my time.

The outline, however, is a good general guideline for any Zope
education.  The outline has evolved from a very simple one to the large
one I posted on the list, and I thought alot about the sequence and
content of each section.  The ZDP is welcome to take that framework and
build around it as a book will probably not be coming any time soon
unless (until!) Zope becomes wildly popular.  And even at that point, it
will probably be best for someone with a better grasp of clear English
writing than myself to compose the actual material referencing from my
notes, technical documentation, and existing documentation.

What is lacking is Zen.  We use the term 'Zen' around here alot, and
like the real world meaning of Zen, it has different interpretations at
different levels and for different people.  I think things that have Zen
are the mechanisms that set Zope apart from other systems.  Things like
Acquisition, ExtensionClasses, ZPublisher etc.  Other may have different
views.  Paul might think that Zen is the process of web application
evolution using Zope as a baseline.  Rob might think Zen is the
simplicity of Zope workflow and distribution of various different data
sources.

People (including ourselves) talk alot about how much of Zope is
undocumented, well, much of it *isn't* but there is a lot of of existing
referential documentation that is quite good, and detailed enough for
someone to bootstrap themselves into the more complex material.  I think
that one of the reasons that new users mention the lack of docs is
because they install Zope and then sit at the management screen and
think, 'What next?'.

Lets look at the big three existing docs, the DTML Guide, the Zope
Managers Guide and the ZSQL Guide.  They are all good and complete user
manuals.  In fact, writing a user manual is one of the *first* steps we
(try to) take around here when developing a new application.  The user
manual drives our use cases and helps us collect our goals and
requirements.  The guides, in good detail, explain all the DTML tags, go
through several use cases explaining how to manage a Zope site, and
detail using SQL servers with Zope.  For people who have the Zen, they
are excellent reference and example materials.  But for those who don't?

This reminds me of an anecdote from the great Richard P. Feynman.  He
spent quite alot of time in Brazil teaching physics.  He was amazed by
the fact that you could ask a student 'What is Boyles law?' and they
would immediately reel off a very technical definition, learned,
verbatim, right from the book.  If he asked, however, 'How can we make
such-and-such gaseous system do this?' (wanting them to apply Boyles law
to a real world situation) he got blank stares.

Maybe I'm getting some blank stares right now. ;) I don't know what the
point of this pointless tirade is, but my goals for The Zen of Zope were
to give the reader very clear reasons for why there is Zen in Zope,
explain that Zen, and show how the Zen and the tools let you do very
powerful things.

-Michel