[ZDP] Zope hierarchy

[Michel Pelletier]

> -----Original Message-----
> From: Martijn Faassen [mailto:faassen@vet.uu.nl]
> Sent: Wednesday, May 19, 1999 11:14 AM
> Cc: zdp@zope.org
> Subject: Re: [ZDP] Zope hierarchy
> 
> 
> Tom Deprez wrote:
> 
> [Michel Pelletier warns Tom for internal complexities -- 
> better focus on
> user docs first]
> 
> > Yes, I know internal Zope is complex. Especially if you've 
> never seen
> > Python. 
> 
> Even if you're seen Python it's complex, I can assure you. Python is a
> very dynamic language, and generally very easy to read, but Zope
> exploits some aspects of this dynamism to the max, and introduces some
> concepts unfamiliar to most programmers (such as Acquisition).
> 
> > I try to form an easy understanding of Zope for beginners 
> (like me). When I
> > openend Zope, I saw lots of products, like ZSQL Methods etc 
> which I can add
> > etc. I played around with them, but what I missed is how 
> they interact with
> > each other. And it's this I want to show in some of 
> schematic overview. Same
> > with Z Framework.... I can't fully get a grip around the 
> ZFramework, ...
> > when does ZFramework comes into play, etc.
> 
> Yes, I agree with Tom that to be able to show a very clear picture of
> Zope for beginners an understanding of the guts of Zope can be very
> useful. It's the Zen thing again -- to present a clear and correct
> picture for utter beginners, deep understanding may be necessary.
> 
> Of course such deep understanding is indeed a big project. :)

I guess the point of my original message was that we are working on some
very detailed and technical oriented documentation material internally,
specificly in the form of UML diagrams and component by component
breakdown.  Eventually, we would like a "building blueprint" like
overlay of the entire system.  Whereas issues like acquisition, site
structure, and DTML can be explained easily in prose, very rigorous
mechanisms are easy to get subtly wrong.

For example, lets say you were explaining the traversal algorithm.  You
could simply say "ZPublisher traverses the objects until it find the one
your looking for".  This is not very hepfull to someone who needs to
know if they can define a __getattr__ method, how __bobo_tarverse__
works, or how the ORB interacts with all these and acquisition too.  Any
Zope Product that is moderately complex may need to delve into these
issues.  Explaining this would require the deepest knowledge of the core
of the system.  Nothing unreachably complex, but it will be much easer
for you guys to document for the "common folk" when we get done doing
the techical documentation for the development community.

However, where you can now fill in is the higher level usage docs.  I
would suggest thinking about a number of use cases, and then explaining
each use case in detail.

For example:

Akbar's company has an SQL database full of customer info, that they
want to publish to their field representitives but not publicly.

United Geeks For Nuclear Disarmament has an ftp site full of .pdf
documents describing the various US atmospheric nuclear tests from 1945
to 1963.  They want to organize the documents online, using a nice
folder/document structure and acquisition to factor out common
components.

Rick wants to write a ZClass that represents all various properties of
the steel casing for drill chucks that he manufactures.  He wants these
objects to be droppable into Zope by his secretary, who is 96 years old
and computer illiterate.


...and on and on.  Think up about one hundred use cases, factor them
down to a common subset of very useful tasks, and then start writing.

Another documentation task that needs to be done is documenting the
upcoming new products, like ZTablesCore, Catalog, IMAPAdapter 1.0, and
the Membership System.  If someone wants to take my technical docs and
expand them into user documentation, I'll send you preliminary versions
of the docs (and I'll look into sending you preliminary versions of the
software, but you'll have to be pretty Zope savvy and be capable of
doing cvs checkouts of the latest Zope without much handholding).

Just think, documentation and it's software released *at the same time*!
;)

-Michel


> 
> Regards,
> 
> Martijn
> 
> _______________________________________________
> ZDP maillist  -  ZDP@zope.org
> http://www.zope.org/mailman/listinfo/zdp
>