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:amos@digicool.com Digital Creations http://www.digicool.com
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:amos@digicool.com Digital Creations http://www.digicool.com
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org 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 )
--On Wednesday, June 06, 2001 11:57:06 AM -0400 Paul Everitt <paul@digicool.com> 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
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.
participants (4)
-
Amos Latteier -
Dan L. Pierson -
Erik Enge -
Paul Everitt