Paul (2000/11/17)
Is it within the scope of this project to promote interface docs for 3rd party apps, such as Squishdot? For instance, the help system not only documents Zope, but is also available for documenting other people's stuff. Will this project help solve the problem of how other people can document and communicate their interfaces? How important is it for this idea of interfaces to be adopted by other Zope developers in their products?
One of the successful things from the Python Library Reference, IMO, is the examples in each section. Is that in the scope of this project?
Talking about thin ice, here goes a whopper. Is there any relationship between this effort and interfaces for Python? For instance, Scarecrow was originally something for Python, not Zope. Should Zope and Python share even 1% of an idea of interfaces?
Paul (2000/11/17)
Here's another risk. Are interfaces contracts for backwards compatibility, or just suggestions? That is, is Zope/DC willing to go on the record in a very measurable way and say, "This behavior will work."Fred (2000/11/17)
Response to Paul's comments above:
For the Python standard library, we consider each case separately. There are times when the documentation is just plain wrong (doesn't match the released implementation), and there are times when the documentation reflects known bugs, and the docs and implementation can be changed in tandem. For other cases, we strive to preserve the documented API. If the implementation works but is not considered as useful as it should be, and backward compatibility cannot be preserved by extending an interface, an additional interface is added (by adding new functions or methods usually).
Comment on organization:
I'd expect the Problem section to come first, just because that really tells the reader more earlier in the proposal. This is a relatively minor nit, but I've always found that this kind of attention to detail makes a big difference in readability.
I reorganized it a bit so the problem comes before the risks. - MichelP?
Comments on the Risks:
These risks are all shared by the Python library documentation. There are a few precedents for describing an interface in the library reference, however: the "formatter":http://www.python.org/doc/current/lib/module-formatter.html module does contain documentation for two interfaces, and "file objects":http://www.python.org/doc/current/lib/bltin-file-objects.html are described as an interface with a reference implementation (notes are included which try to distinguish between implementation and interface requirements; success is questionable).
ChrisW? (2000/11/21)
Well, I did actually document Squishdot's interfaces back when I was learning the code: http://zope.nipltd.com/Squishdot/Squishterfaces/FrontPage/map
Of course, it's out of date now :-S
The important thing for me is that Interfaces documentation provides an interface contract for a specified set of versions of the product. So, for a contrived example:
- <PRE>
File Squishdot.py - Class Squishdot -- Method do_something
for Squishdot version 0.3.4-0.4.0:
def do_something(self,one_param)
one_param - The text to print
This method prints the text supplied in the parameter.
for Squishdot version 0.4.1:
def do_something(self,one_param,two_param)
one_param - The text to print two_param - The numebr of times to print the text
This method prints the text supplied in the parameter a specified number of times.
</PRE>
Of course, I'm sure the UI to this documentation could be better thought out. But, with what I've said, you know whne documentation is out of date, and you know what should work. It can be used to help with backwards compatability, but, by the way it works, when things do change, the documentation will reflect this.
Karl 2000-11-21 --
Responding to Paul and Chris about standards, artifacts, and third party documentation - However we produce a collection of documents, bad content somewhat reduces the value of all of it, because it reduces a developer's willingness to trust any of it. We don't know what the artifacts we're talking about are yet, but whatever they are, they'll need to be kept up to date - that's another risk. So if we promote 3rd party documentation to be added to this pile, I suspect that somebody will need to vet it, or we'll need some other encouragement. There will always be bugs in documentation, just like for any other engineering artifacts, but it's a process to keep them manageable - maybe coding guidelines that include interface strings that an automatic reader picks up, and we promote 3rd party products that follow these guidelines, with the idea that docs for those will tend to be more accurate.
<hr solid id=comments_below>
- lasren (Jul 22, 2001 11:25 am; Comment #1) --
- As a zope newbie I would like to see the documentation projects happen for zope and third party apps. I'm in that sort of good bad place where I know just enough to get my self into trouble. I would also like to see documentation designed for the user level. To me this does mean examples with explanations and definitions of jargon. I'd be happy supply input as a newbie. I'm also happy to post in a more appropriate place if someone could direct me.