Re: [Zope-dev] [Announce] API Documentation Fishbowl Project
--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
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
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
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
--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
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 )