--On Wednesday, June 06, 2001 11:50:43 AM -0700 jimbo <jimbo@tacomaplace.com> wrote:

I hope this helps. I wanted to add my feelings on the whole documentation issue. It seems to me that the whole process caters around developers too much.

...

I have to disagree with you **in the context of this thread** for two reasons:

Why disagree **in the context of this thread** at all? Alot of things change quickly in this field, so flexibility is a must to me.

...

1. DC has done a lot to improve the documentation for non-developers >> in the last year. The Zope Book(s) should have a major impact when they >>start to appear on shelves in the next month or so.

My point

...

Developer documentation has lagged behind.

There still is alot of progress being made in that direction

...

This thread is about a proposal to improve developer documentation. It says nothing at all about the other *existing* efforts by DC and others to improve other types of Zope documentation.

I think you have a misunderstanding of freedom and opensource all in one topic. I'm don't follow you here since I know it helps to get feeback from users of a product. I'm talking about improving the API documentation. I seriously wonder how good that API is going to do me if I can't use it in the workplace today or next week. Everyday I see post like this http://lists.zope.org/pipermail/zope-cmf/2001-June/007427.html excerpt "I'm having trouble using the Guard expression in DCWorkflow 0.2. Everything else works fine; it's a great product. I think the call to expr() in the ...... I do not really know what I'm doing there... but it works :) " My point is Python is/was suppose to be this language so easy and simple that it should be the first language to teach a person. Where does that simplicity get lost with Zope I wonder? Don't even answer because it does'nt matter to me or the other it departments that are going with other solutions. So go on while the confusion is there. Go ahead and justify it now by saying polishing the API will do it for the masses. When you look at the big picture the developer is the smallest user group of any software product.( you have the end-user, testers, admins,etc) That's why it's even more important to make sure the API docs make it easy to implement something and not "wow this is so cool and has so many features" without the benefits. I also think a pretty good example is what Ty and Phillip did with ZPatterns. They had plenty of how-to implement in the API Documentation. It did take alittle while though, but thanks many times over for the learning experience it was fun. In other words half scientific facts(This is)/ half hocus pocus(Do This).

...

2. One of the main points DC made at this years Python conference was >>that they have tried to focus the Zope core on too many audiences at >>once. Yes a problem.

...

They had to have a clearer focus and chose developers as that focus.

Of course they did. We're talking about "Core" services here. Like I said before once again I think it's the impletation part I'm stuck on.

...

Of course I like this choice because I am a developer, but the more important >>point is that this tighter focus has the potential to make life easier for >>all of us.

No just developers. You can call it what you want, but it is a tool that developers can use to get a job done. Content mangers and other network admin types about the API anyway. I imagine most if not all of zope users are progammers in some sense.

...

Incremental restructuring of the Zope core and improved Zope >>developer documentation makes it much easier and more practical for DC and >>others to create layered Zope products that address other communities.

Seems to be my point also. Perhaps I stepped in some fishpoo and need to learn how to get involved with the "Fishbowl" process. Thanks, Jimbo