[Zope-dev] ] [Announce] API Documentation Fishbowl Project

2001-06-08 Thread jimbo

--On Wednesday, June 06, 2001 11:50:43 AM -0700 jimbo 
[EMAIL PROTECTED] 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


___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



[Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-08 Thread jimbo

Or how about this person?
http://lists.zope.org/pipermail/zope-cmf/2001-June/007435.html


oh oh a storm gotta go
-jimbo

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-07 Thread Dan L. Pierson



--On Wednesday, June 06, 2001 11:50:43 AM -0700 jimbo 
[EMAIL PROTECTED] 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:

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.  Developer documentation has 
lagged behind.  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.

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.  They 
had to have a clearer focus and chose developers as that focus.  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.

For example, the CMF is focused on content managers.  It is implemented as 
a *separate*, *layered* product on top of Zope.  This means that it is free 
to make tradeoffs in favor of content managers that the Zope core isn't. 
It also means that CMF release schedules are not tied to Zope release 
schedules.

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.  Continuing 
the current rather inscrutable nature of the Zope core makes all of this 
harder for everyone involved.

Dan Pierson,
Control.com, Inc.


___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-07 Thread R. David Murray

On Wed, 6 Jun 2001, jimbo wrote:
   I believe that if you are a true developer you will/can figure out the api given 
the vast information available today.
   For example the dcworkflow product was just released. I believe the best 
documentation would be  how-to actually use the product.

Ah, not really.

Or, rather, maybe, with the *new* products whose APIs are being
constructed/documented better from the start, but if and probably
only if there are either comprehensive examples or the framework
docs mentioned in the proposal. 

IMO the biggest issue here for developers, as others have said, is
clarifying/documenting the old Zope interfaces.  If we get that,
then new products will be even better/better integrated.  This
includes ZClasses.  Half the problem with ZClasses is that they
sort of almost work, but they break down partly because the interfaces
really aren't documented very well.  (I strongly recommend learning
python.  It's an easy language to learn.  Then use real Python
classes instead of ZClasses.  ZClasses have their place, but if
you are doing serious development they tend to get in the way more
than they help, IMO).

In short enough geek speek.  Change the language into something the rest of masses
can understand.  How can I use zope/API to get PAID!  How can I actually make the
dcworkflow or the core session or the ZPT do something.  Plenty of example uses. I
think they might call them case studies or something to that effect.

How can I actually make x do something sounds an awful lot like
what I think the framework docs portion of the proposal is
addressing, when you are talking about components like workflow
and coresessiontracking that are used to *develop* applications.
I think you will find that good API+framework documentation will
either provide a good deal of the info you are looking for, or,
for products that are less in the way of infrastructure components
and more in the way of end user products, provide the essential
foundation upon which more end-user directed documentation can
built.  Good end user stuff is best written by someone who understands
how the product works in detail, and the API/framework docs provide
the foundation to acquire that knowledge (assuming the product
author himself doesn't go straight on to providing the end user
docs).

How to get use the API to get paid is, I think, outside of the
scope of the proposal grin.

As for the proposal itself, the mechanism outlined sounds OK to me.
I do also have an issue with the Interface scarecrow in that it does
not seem to cover stuff that is not specifically a Class interface.
I'm thinking of module level functions in particular, but also
the documentation of Protocols mentioned by another poster is of
concern.  So Interfaces by themselves do not seem to be enough.
Where they are enough, though, I should think there would be nothing
stoping someone from writing one for an existing Zope internal
interface, without modifying the code (ie: no automated verification
in that case).  Of course, I suspect that anyone doing that grubby
job would tend to want to start tinkering with the code to clean
up the interface...which come to think of it might be something
that should go in the risks section wry grin.

On the third hand, there's nothing to stop the community from
generating some this is how I think it works documentation
that people with inside knowledge can then help tune.  I think
some of this happened during the original Interfaces Wiki days,
and it seems to have produced good results.

I also want to say that I really like the fact that this proposal
makes it clear that DC understands the long term value of good
developer documentation grin.

Oh, and one final thought.  It seems to me that the Developer's Guide
needs to evolve into a meta framework document: a place to learn
how the whole system fits together, and how you use the various
components to build working systems.  I think it's a solid start
in its current form.

--RDM


___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-06 Thread Paul Everitt


Hmm, I'm surprised that 2 days has passed with no comment from zope-dev
and no comments in the Wiki.  I hear constant complaints about lack of a
polished API.  I expected this post to generate lots of interest.

What say ye, zope-dev?  Is this something we should be doing, or would
you prefer a different documentation activity to have priority?  Is the
proposed solution agreeable?

For all of you that have chimed in about the API, here's a chance for
you to get involved and help make it a strong effort.  Help!! :^)

--Paul

Amos Latteier wrote:
 
 Fellow Zopistas,
 
 Mike Pelletier and I are working on a project to improve Zope's API
 documentation. Details are now publicly available in the fishbowl.
 (Actually it's been public for a while, but this is the first
 announcement of the project.)
 
   http://dev.zope.org/Wikis/DevSite/Projects/APIDocs
 
 I encourage you to check it out and leave your comments, criticisms, and
 suggestions.
 
 This project aims to improve the life of Zope developers, so please help
 us make sure we're not off base. For the project to succeed it must meet
 *your* needs.
 
 Thanks!
 
 -Amos
 
 --
 Amos Latteier mailto:[EMAIL PROTECTED]
 Digital Creations http://www.digicool.com
 
 ___
 Zope-Dev maillist  -  [EMAIL PROTECTED]
 http://lists.zope.org/mailman/listinfo/zope-dev
 **  No cross posts or HTML encoding!  **
 (Related lists -
  http://lists.zope.org/mailman/listinfo/zope-announce
  http://lists.zope.org/mailman/listinfo/zope )

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-06 Thread Erik Enge

On Mon, 4 Jun 2001, Amos Latteier wrote:

 I encourage you to check it out and leave your comments, criticisms, and
 suggestions. 

I like.  That pretty much captures it :)

There is one thing, though.  Let's say I have this class NiceBigCar.  The
developers docs from what you suggest are fine, but how about semantics
for adding users/clients/otherpersons docs as well?  I know it's only
documenting API's but surely the users use the API at some level too.

Is it meant to be like this:

   NiceBigCar/
  doc/
  dev/
  user/

for example?

I love the AOP stuff and I can't wait to start fiddling with it (once TW
is out for Python 2.1) and I just wonder if there is an easy way of
combining this weaving-effect with documentation.  I don't know, it might
be out of scope, or maybe the proposal takes care of that already, just in
a different way.


___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-06 Thread Dan L. Pierson



--On Wednesday, June 06, 2001 11:57:06 AM -0400 Paul Everitt 
[EMAIL PROTECTED] wrote:


 Hmm, I'm surprised that 2 days has passed with no comment from zope-dev
 and no comments in the Wiki.  I hear constant complaints about lack of a
 polished API.  I expected this post to generate lots of interest.

I read it over, the final design seems acceptable if docs are actually 
written to it.

My main concern is the one that Chris McDonough expressed in great detail 
in the wiki, namely that definining the (existing) interfaces is THE 
critical step.  Simply documenting all of the methods of objects is not 
sufficient because it says nothing about which are important, which are 
internal only, which are obsolete, how they interact, etc.

The final design does base the API on hand-written interfaces, which is 
good.  There is also some seemingly fuzzy plans to have an interface 
verification tool, which will be of some value in catching some cases of 
non-compliance.  However, the vital hard bit of creating the hand-written 
interfaces and ensuring that they're right is sort of glossed over in my 
opinion.

I thought of adding some of this to the wiki, but it all seemed to amount 
to a redundant me too and I wasn't sure where to put it :-(

Following the spec for newly written products should be easier.  The CMF 
seems to me to be a good example of a product that has done so (though the 
interfaces seem to be getting out of date at the moment).  I have found 
online CMF API docs useful in practice.

Dan Pierson


___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



[Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-06 Thread jimbo

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 gotta tell you 
I loved Zope the moment I found it.  These days I'm having trouble though wondering 
what is it all for? I've used zope for the past few jobs and the customers did not 
have any interest in using zope so they changed the sites. 

  I believe that if you are a true developer you will/can figure out the api given the 
vast information available today.
  For example the dcworkflow product was just released. I believe the best 
documentation would be  how-to actually use the product.

One thing would be to adjust the documentation to spoon-feed to the masses zope and 
all the wonderful things that people can do with it now!

If you spend too much on wooing developers and not the types doing the hiring, you 
might just end up being a small niche serving hobbiest who do this for fun.

  Please don't banish this wonderful product to Eternal Geekdom by not simplifing the 
documentation by putting together concrete examples on how to implement concepts and 
products.

In short enough geek speek.  Change the language into something the rest of masses can 
understand.  How can I use zope/API to get PAID!  How can I actually make the 
dcworkflow or the core session or the ZPT do something.  Plenty of example uses. I 
think they might call them case studies or something to that effect.



Thanks,
-Jimbo

 

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



Re: [Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-06 Thread Eric Roby

Jimbo, I concur 100%.

I am a Zope newbie (relatively speaking - since February) but I have been
developing Web Information Systems since '95.  My tool of choice was
perl/CGI.  I attended a DEVX conference in December of '99 and was
introduced to Java Servlets and the J2EE spec.  I knew this was the
transition that I had to make, professionally.  However, 100% of my work
evolves around information management and publishing.  J2EE doesn't
immediately solve this requirement without a great deal of tooling. I saw
the benefits of the enterprise but couldn't justify the effort (to my
customers).

In walks Zope and the lights/whistles/fireworks went off.  Zope immediately
provides me the vehicle to move from a 'Cottage Software' paradigm to a
(sort-of) 'Industrial Software' paradigm.

I am no python programmer, yet.  But, with the other available tools (DTML,
acquisition, ZClasses), I have been able to get the job done.  I have hit a
few land-mines since February.  In some cases I was able to work through the
problems from How-To's, others from the mail-listings.  But a couple of
problems have yet to be resolved. The new Zope Book is a step towards
consolidating all these other doc efforts but it falls short on utility. I
have many perl books on my book shelf.  The one that I always go back to is
my original 'Camel'  book.  Wall  Schwartz put the right mix of fact, fable
and 'case studies' to get the imagination brewing.  I don't need my hand
held but I would greatly appreciate some insight on what is possible and
what is not.  The biggest stumbling block for me to date (and potentially
the most powerful tool for me) has been connected with the nuances of
ZClasses.  The examples in the book gloss over the implementation details
that would be the most instructive and could have saved me days of searching
and swearing.  I ended up searching for some ZClass products and worked
through them to fill in the blanks.

I see enormous potential for Zope in the Peer-to-Peer revo/evo-lution.  I
want it to succeed.  I scream Zope at every opportunity.  But, I have
invested nearly 800 hours of my time to be able to talk-the-talk and now
walk-the-walk.  I feel quite comfortable in recommending this system as the
final solution as we move to P2P.  Not everyone can afford that kind of
commitment.  The people paying the bills certainly won't.

Certainly, the API documentation could be presented better, but expand on
some of that brain-storming that is going on behind those DC doors (well not
all of them ... you guys need your trade secrets too), those 'what if'
scenarios that would go a long way towards enlightening the masses.

Eric

   Please don't banish this wonderful product to Eternal Geekdom by not
simplifing the documentation by putting together concrete examples on how to
implement concepts and products.

 In short enough geek speek.  Change the language into something the rest
of masses can understand.  How can I use zope/API to get PAID!  How can I
actually make the dcworkflow or the core session or the ZPT do something.
Plenty of example uses. I think they might call them case studies or
something to that effect.



 Thanks,
 -Jimbo

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )



[Zope-dev] [Announce] API Documentation Fishbowl Project

2001-06-04 Thread Amos Latteier

Fellow Zopistas,

Mike Pelletier and I are working on a project to improve Zope's API
documentation. Details are now publicly available in the fishbowl.
(Actually it's been public for a while, but this is the first
announcement of the project.)

  http://dev.zope.org/Wikis/DevSite/Projects/APIDocs

I encourage you to check it out and leave your comments, criticisms, and
suggestions. 

This project aims to improve the life of Zope developers, so please help
us make sure we're not off base. For the project to succeed it must meet
*your* needs.

Thanks!

-Amos

--
Amos Latteier mailto:[EMAIL PROTECTED]
Digital Creations http://www.digicool.com

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )