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 )



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 )