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

Paul Everitt Paul@digicool.com
Thu, 19 Aug 1999 13:42:37 -0400


Lindon wrote:
> 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).

There are three main reasons you haven't seen us jump in with answers:

1) It isn't completely clear what is the question.  The world
"documentation" means different things to different people.  What's the
greatest need: reference material, tutorials, questions and answers?
Who gets attention first -- new users or deep programmers?  Everybody
will have different responses, and we need to be prepared to give good
ones.  Which leads to...

2) The value of us making off-handed replies is zilch.  We can continue
spreading feel-good vibes promising some just-around-the-corner
progress, but nobody's going to buy it.  We need to make a response that
shows we've listened and thought about the discussion, and are proposing
something we are going to follow through on.  It's commitment time, not
fast response time.

3) Finally, we are chasing _very hard_ the server lockup issues, making
fixes and testing them.  This _must_ be the priority right now.  People
won't tolerate broken, but documented, software.

With that said, _pleeease_ take this discussion over to the ZDP list
before we chase off all the subscribers on this list!  Please, please,
please!

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

Correct.

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

I completely understand your desire to have this, just as I completely
understand the other desires for different, but needed documentation.
There's no why Michel was going to drop what he was doing and write the
definitive, professional, permanent answer to your question.  However,
he obviously took out a chunk of time to give you his impression of what
you were talking about.

Michel spends a LOT of time responding to messages.  Many of his answers
in fact *are* "here's the code" kind of responses.  Others here do the
same.  I don't think the fault is that we aren't doing anything, rather
we aren't doing anything organized.

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

Understood.  We are also told that Vignette is the kind of "content
management system" in Zope's space.

>    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 

Hmm, how many pages of documentation have they written already for a
product that won't ship for 8-12 months?  Are you basing your assesment
on the docs that you get for ColdFusion now?

Also, since most people don't have the ColdFusion docs at their disposal
(after all, you have to pay to get them), could you instead provide an
example of an open source project that has good docs that Zope could use
instead as a goal?  For example, I felt like the PHP crowd does a great
job of boostrapping new users.  Python does as well.

> 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 

Yes, there is ticket price, annual support and maintenance, future
upgrade charges, developer seat licenses, costs for new CPUs if your
business grows, etc :^)  The point isn't that the customer's aren't
willing to pay for it.  Rather, this is the money that helps fund the
packaging.

IMO, if we at Digital Creations provided docs that were as informative
as the "big three" in Python (the tutorial, library reference, and
language reference), then we'd have an arguable case to say we have
caught up.  Maybe not with ColdFusion, but with that which should be
expected of us.

At the same time, if the community could collect the incredible amount
of wisdom that is out there, we'd have an arguable case for exceeding
what you've described.

> one(small) component in the overall cost of software, poor 
> documentation is 
> another soaring cost to organisations such as ours.

Yep, that's true.

>    So the only real advantage left is the 8-12 months window, 

Hmm, I'm not sure I really agree that it is the only advantage, but the
response isn't germane to this argument.

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

Though I disagree with the assertion that Allaire doesn't have any
weaknesses of its own, I certainly agree that reasonable docs are
mandatory.

Again, our lack of response is for one simple reason: we want to make an
informed response.

--Paul

Paul Everitt       Digital Creations
paul@digicool.com  540.371.6909
-----------------------------------------
The Open Source Zope application server
http://www.zope.org/