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

[Michel Pelletier]

> -----Original Message-----
> From: Lindon Parker [mailto:twomoonlp@hotmail.com]
> Sent: Wednesday, August 18, 1999 10:04 PM
> To: zope@zope.org
> Subject: [Zope] Re: getting some documentation going:(getting long
> here..)
> 
>     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.

You're right.

>    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.

Method A:

<form action="B">
  <input type=text name="PrincipiaSearchSource">
  <input type=submit value=" Search ">
</form>

Method B:

<dtml-in Catalog>
  <dtml-let URL="getpath(data_record_id_)">
    <a href="<dtml-var URL>"><dtml-var URL></a>
  </dtml-let>
</dtml-in>

Will create a simple search box form that let's you free text search all
of the objects in the Catalog ('PrincipiaSearchSource' is the attribute
to get searchable content from text objects like DTML Documents/Methods.
The Principia should probably get whacked).  To actually *Catalog*
objects go to the Catalog, click on 'Find Objects' and enter the find
criteria for the Catalog.  It's quite intuitive (of course, I wrote it,
it might be clear as mud to you)

> 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 

Yes it does.  The final 2.0 release will come with a Catalog pre-indexed
to the default Zope content for you to play with.

> 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. 

We have similar needs, altough not necesarily competition driven.  We
need to move onto more consulting work which will require more
documentation for our paying customers.  Otherwise we loose money
answering questions that could just be documented.

> 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.

I wouldn't say poor documentation is a cost, but it is a contributing
factor to high costs.  As an example, it took me about three man-days
(over the course ofa week) to find enough documentation on the new Linux
software RAID to get it right.  ALl the faqs, howtos, and source docs
were out of day.  In fact, there were three 'official' RAID homepages,
each with a different version of the software at various points in it's
development stages and for various kernels.  It was maddening.  I know
how you feel.

Trust me, we're on it.  We're not sitting back and ignoring all of these
threads on documentation.  There are also some recent developments that
cannot be discussed at the moment (think bound sheets of paper) that
will bring us into a serious light with people who like docs.

-Michel