[Zope] Re: Zope reference documentation?

[Chris McDonough]

On Thu, 2003-01-16 at 10:06, Patrick Price wrote:
> Now I am committing to myself to re-write a sample chapter to see if I 
> can actually do something about the documentation problem.  

Thanks!

> 
> I find my main complaints with the Zope book are that it uses a lot of 
> things such as "examples", or "what have yous" in a lot of "quotes" 
> which makes it, for example, such as, "hard to read!"  Yackety 
> Shmackety, right?  I'm not slamming anyone's writing style - just 
> looking for validation that I'm not the only one and that I'm on the 
> right track.

This is a valid complaint..  Now that I've read it again, "quoting" is
somewhat overused.  I am largely unaware of doing this when I am
writing.  I think in most cases, my purpose in doing so is to ensure
that folks know a word that I'm using is a "normal" word instead of some
kind of domain-specific keyword that has a formal definition that they
need to understand.

> This may not be the place for it, but here's my re-write (all original 
> with bits of the original text) of the first part of the "Object 
> Orientation" chapter of the 2.6 book.  -Patrick Price  

This probably isnt the place for it, but I do appreciate the effort.  If
you get motivated to do more editing, please send me the entire chapter
via email and if it makes sense, I will re-edit what you've done for
inclusion in the book when possible.

Below I comment on your edits.  I hope you don't mind that I point out
some flaws in your rewrite.

> Object Orientation
> 
> There are many programming languages based on Object Orientation (OO), 
> and Zope is based on the Object-Oriented Programming (OOP) language 
> known as Python.  To understand and use Zope for creating anything but 
> simple web sites, you must understand how OOP controls every behavior of 
> Zope.  Zope's foundation is built on object-orientation, so it follows 
> that if you master OOP, you will master Zope.

OOP doesn't control every behavior of Zope, although it does permeate
Zope.  For example, there is lots of procedural code in a typical Zope
application.

>  
> Object-orientation is a programming paradigm in which all logic (the 
> actual programming and scripting) and data (folders, files, databases, 
> etc. ) are treated as objects.

Does it make sense to define object orientation as a system in which
things are "treated as objects"?  This sounds a little sketchy. ;-)

> Viewing everything you work with as an 
> abstract object allows you to focus on a high-level view of your 
> application, rather than getting bogged down with details like file 
> descriptors, handles, and other low-level programming chores.

This is a good sentence.

> You may 
> think of objects as building blocks, which can be comprised of bundles 
> of smaller things such as data, programs, variables - even other 
> objects!  By categorizing your data and logic - your problems - as 
> objects, you will find that you can break up large problems into smaller 
> problems, block by block.

I'm not sure how this is any more clear than what the current chapter
says.

> This level of abstraction helps you develop clear design solutions, 
> perform rapid prototyping, and results in an efficient, well-structured 
> application design. 

Objects themselves help you do none of these things, although proper
usage of objects in an overall application design does.

> Objects
> 
> Prior to the OOP paradigm, data was viewed as separate from program 
> code, or sometimes mixed together without a clear delineation between 
> them.     Now, with OOP methodology, your data and logic can both be 
> stored in a single object.

This makes it sound as if OOP is a new dishwashing detergent. ;-)  OOP
implementations have been around since at least 1962 (Simula was the
first OO programming language), and it's likely that the concept existed
before that.

>     Objects provide a clear and distinct 
> separation of data and logic within themselves.   Zope treats every 
> thing as an object, whether it is, for example:  a filesystem directory, 
> a folder (container for other objects), files, modules, products, 
> templates, forms, spreadsheets, spreadsheet cells, databases, database 
> records, phone #'s, addresses, scripts, programs, calendars, buttons, 
> URL's - Anything!

Zope doesn't treat these things as objects at all.   Your code might,
but Zope knows nothing about them as objects until you teach it to do
so.

> 
> There really is no limit to what can be called and modeled as an object.  

This is a nonsentence. ;-)

> 
> In your journey to understanding Zope's object-oriented framework, you 
> may continue to think that data is just that - plain old data.   You 
> must leave those thoughts behind.

No.  You don't need to leave them behind.  Zope works with "flat" data
too (via RDB).

> Once anything - even a simple text 
> file - is stored in Zope, it becomes  an object.

This is arguable.  What does "stored in Zope" mean?  I realize that it's
a simplified example and what you probably really mean is "items that
are visible in the Zope management interface which are instances of
classes, stored in the Zope object database", but this more detailed
description is obviously too much to chew off conceptually for the
reader in this chapter.  It might be best to just not go here.  This is
a chapter primarily describing object orientation, and isn't as much
about how it relates to Zope.

>    The associated 
> details of the file, such as the file type, size, and location are 
> stored along with it  and become collectively known as the attributes of 
> the object.   Even the file data itself is considered an attribute of 
> this newly-created file object.

This is a good example...

> In the same manner a mere program 
> becomes  an object when it is stored in Zope.  Programming, scripting, 
> code, logic - are then referred to as the methods of the object.

What are referred to?  What object?

> 
> Thus, an object is comprised of attributes and methods.

You don't define "method" at all.

Cheers,

- C