[Zope] Re: getting some documentation going:(getting long here..)

Lindon Parker twomoonlp@hotmail.com
Wed, 18 Aug 1999 19:03:35 PDT


Oh dear, first it's nice of Michael to send a reply. But can any of you 
Digital Creations people see what the problem with the answer? Well before I 
go critcising it, first let me say I'll have some off-list discussion with 
Michael to see if I can get the sort of documentation going we need. But 
(and I'm sorry Michael to be picking on you - I KNOW its not you fault) what 
those "giving up in frustration" people are talking about is the fact that 
there is NO answer here(as is often the case in other replies/documentation 
- obviously NOT written by Michael by the way).
    This reply tells me how great ZCatalogue is(how fast etc. etc.) and how 
I can work with ZClasses(if I design them "right"). In effect this is a 
piece of either developer enthusiasm(always good to see) or marketing 
blurb(and if your frustrated already you can easily pick this option - I'm 
choosing not to by the way). So what this doesn't do is tell me how to 
search Zope objects by attribute value, which was the question I asked. It 
is in turns too much information and too little.
   So what I want to see is a simple piece of code that lets me search my 
Zope database where I can, as a complete novice, substitute my objects and 
my attributes to get back a list of things I can itterate over. Lets ignore 
perfomance, b-tree's, ZClass design etc. etc. Assume I have NOT installed 
ZCatalogue(unless of course it comes by default on my NT Zope 2.0 install, 
does it?), and I'm using DTML Documents. In short assume I am an idiot(you 
wont be so far wrong) but I need to get something working pretty quickly, 
and I'll make it graceful later.

OK now the specifics are out of the way I want to quickly offer up a view on 
why we need to stop the development process(or slow it down severely) and 
address the documentation issue. In a word "SPECTRA". This is the new 
content management tool from Allaire, based on their ColdFusion web/database 
interface. Recently Allaire were out here doing demo's and training, we were 
invited, and attended. So basically it's in the same domain as Zope and it's 
VERY powerful. It will not by the way be the last product in this domain, 
but right now it's shaping up to be the competition for Zope. Now I don't 
really mind if Digital Creations don't think it is the competition, it is as 
far as potential customers are concerned(well the potential customer I work 
for anyway).
   The good news is that it's about Aus$12,000 per copy and wont really be 
ready for prime time for about 8-12 months(we think). The bad news is that 
it WILL ship with VERY VERY good documentation. In fact the ticket price 
isn't such a differentiator either; anyone (including you guys at DC) who 
thinks Zope is free is really fooling themseleves, ticket price is but 
one(small) component in the overall cost of software, poor documentation is 
another soaring cost to organisations such as ours.
   So the only real advantage left is the 8-12 months window, which we need 
to use for documentation. Now we might all think Zope and the python/OO 
technologies around it as well as its inherent design, flexibility, 
extensibleness means we have a better product here, and that only a deluded 
fool would use a relational based  blah, blah, blah product. But the reality 
is that Allaire will beat us out here(they have a lot of experience with 
volume delivery) if we don't meet them on MANDETORY issues like good 
documentation. We have an opportunity to keep this area of our industry 
open, with the use of Zope. But it will pass us by if we dont get good 
documentation soon.
   This is but one of a range of arguments made here for getting on the 
documentation-for-dummies bandwagon.

Phew that got really long, sorry to take so much of your time.
Lindon

> > And whilst we're here if you'll tell me how to search through all the 
>Zope
> > objects in my site by some attribute and then display some (other)
> > attributes, basically like a SELECT statement but not on a database 
>instead
> > on Zope itself(see I'm really new) I'll write that FAQ/chapter too...
> >
>
>Well there is, of course, more than one way to skin this cat. Before
>Zope 2.0, there was the find machinery, which would brute force search
>through your objects looking for ones that matched certain criteria.
>This is, of course, not very efficient for the same reasons that full
>text indexers don't use command line tools like 'find' and 'grep'.  They
>are good one time use tools, but not efficient for lots of searching.
>
>Zope 2.0 introduces ZCatalog.  ZCatalog is a very flexible and powerful
>tool, and thus, probably requires lots of documentation.
>
>ZCatalog works one of two ways, first, you can use the aformentioned
>'Find' machinery to find objects on your Zope and 'catalog' them.  This
>means that if a found object has an attribute your looking for, the
>value of this attribute is stored in the catalog is a very fast BTree
>like data structure.  By fast, I mean less than a second to find one out
>of a million cataloged objects (my book on BTree theory says that
>average case it takes only 20 simple comparison operations to find one
>out of one million items, so it's probably a lot less than one second).
>
>The tradeoff is speed for memory and database consuption.  Since the
>catalog is storing lots of information about the object, such as
>references to its values and such, ZCatalog can bloat your
>database/memory footprint.
>
>The second way ZCatalog works is trasparently with ZClasses.  If you
>design your ZClasses right, they can automaticly catalog and uncatalog
>themselves as they are created, destroyed, edited, and moved around
>Zope.  This is wildly useful for things like News items.  If you create
>your own 'News' ZClass that properly catalogs itself, you can create a
>fully text searchable News system with little maitenance overhead.
>
>Oh did I mention ZCatalog can fully text search?  That's right, one of
>the indexes ZCatalog can create are 'TextIndexes'.
>
>Thankfully ZCatalog comes out of the box fairly well preconfigured for
>Zope.  Granted, you must add any additional attributes you want to find
>that don't come stock, but be default ZCatalog will index id, creation
>time and meta_type, and text index title and text content (if there is
>any).
>
>Note that ZCatalog does *not* create search forms for you.  But a good
>template form and report document can be generated by the 'Z Search
>Interface' wizard by selecting 'Add: ZSearch Interface' in Zope and
>selecting the Catalog you wish to point the search form to.  You can
>have as many types of search forms as you please.
>
>There will be *many* upcomming usage examples in the new zope site,
>which uses the Catalog extensivly on almost every page.
>
>-Michel
>



______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com