[Zope] Re: reality check - The REAL issue

[Bill Anderson]

Sam Gendler wrote:

 
> Additionally, zope seems to be at a critical juncture, as it starts to get media
> attention and market mindshare.  However, all the attention consistently focuses
> on usabililty at some point.  I really do think it is time that the __zope
> community__, lead by DC, do something to provide adequate documentation, and to
> perhaps clean up some of the usability inconsistencies at the same time.  To all
> of the complainers on this thread, why don't you pick one small area of the
> current docs that you think are insufficient, and do what you can to improve
> them.  I am sure that DC and the ZDP will do what they can to provide detail that
> you are lacking, that you can then add to the docs.
> 
> I see an awful lot of questions about running PCGI and FastCGI on Apache, Roxen,
> ApacheNT, and IIS.  I also see certain people consistently providing the answers
> to the questions.  last time I looked at the ZAG, there was no detail about how to
> do this.  How about those people that have working installs of Zope with another
> webserver submit configs to me, and I will compile them into a document providing

For Roxen, you can see the two howtos, IMO, they document the process
quite well, all things considered. :-)

> working examples.  However, I would like at least a single line description of
> what your Rewrite rules are doing, especially if they are doing anything out of
> the ordinary.  Particularly those folks with fastcgi experience, this would be
> very useful.
> 
> If someone else with some ZClass experience wanted to write up instructions for
> writing a ZClass stub in python, which is mentioned as possible in the ZDG, but
> with no instruction on how to go about doing it, I would find that exceedingly
> useful.  I managed to hack some things up from ZDiscussions, but that was by
> writing a self contained base class that was inherited by the ZClass.  I want to
> know how to write python code that belongs as part of the ZClass, and I have no
> idea how to go about doing that.

I'll second that. IMO, much of the complaints about the dtml complexity
is due to trying to do it all in dtml. ISTR in the first docs put out on
Zope (then Principia), was a statement warning that if you were doing
much control structure statements in dtml, you should probably be
looking at doing it in Python. I know Python somewhat well, but would
relish more documentation on doing zope-python (ZPython ;). It may just
clear up some of the dtml issues, IMO.

> 
> If someone wanted to document how to use the _  namespace with some real world
> examples, so that people without python experience could decipher that page of the
> dtml guide, that would be tremendously useful and should cut down on a lot of
> traffic on the list.
> 
> There is no need to contribute an entire document to the current zope docs.  Just
> put together a more easily understood version of a current page and I am sure that
> some at DC will get it integrated with the docs.
> 
> If someone wanted to go through the How To's and get them integrated into the
> correct places in the docs, that would be terribly useful to.  Why are we waiting
> for DC to do it.

IMO, it has been due to a lack of understanding of DC's position, which
was briefly outlined in thi svery thread. The last I saw, the docs were
written using a proprietary tool that many of us aren't willing to buy.
That certainly doesn't help. (No, let us not drag up the rest of that
thread, please.).

Bill



-- 
In flying I have learned that carelessness and overconfidence are 
usually far more dangerous than deliberately accepted risks. 
          -- Wilbur Wright in a letter to his father, September 1900