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

[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