Vision
This is a work in progress, please leave your comments in the APIReferenceDiscussion page
To develop referential documentation for working with Zope objects and components from a programmer's perspective (DTML, Python, Perl etc.).
Scope
The scope of this project is to define what a Zope interface is, how documentation for those interfaces should be written, and to write said documentation.
There are many, many examples out there of successful API documentation. One particular example we can take a lot of direct experience from is the Python Library Reference. In particular, we don't necessarily need to re-invent any wheels to get very far along on this project.
Third party developers need to be able to provide interface documentation for their products that can, at the least, fit into the presentation of "offical" APIs with minimal effort without tying them to specific policies.
Problem
The internal interfaces of Zope are not documented. Because of this, Zope developers must rely on source-code introspection to understand how to develop for, or extend Zope. This leads to:
- wasting time going through the same labors as other developers.
- Possibly misunderstanding how interfaces work, causing errors.
- Using methods and attributes that aren't part of the "real" interface, writing bad code and possibly propagating its misuse.
- developers being discouraged by the difficulty of the task.
- developers discouraged from writing their own interface documentation.
These problems are exacerbated by the fact that:
- There is no central, organized repository of interface documentation.
- There are no pedantic examples of using Zope interfaces.
- Users cannot easily contribute interface documentation once they understand an interface (through discussion or introspection).
- Any documentation about interfaces that currently exists (for example, in "How-To" format) is not discoverable as an interface per se, and has no quality assurance process or guarantee of accuracy.
- There is no way to track changes to Zope that change interfaces, and possibly break components dependent on them.
- There is no "contract" with users, assuring them that the interface they use is trustworthy.
- Developers cannot write their own third party interface documentaion and present it to the user in a useful way in conjunction with "official" core interface documentation. For example, a developer may want to provide an interface for "Foo" (third party) and cross-reference that interface with "ObjectManager?" (official).
Currently, there is user level documentation for web-scriptable objects in the OnlineHelpSystem? but there are many more interfaces below this level in Zope that need to be documented.
Risks
- There is no concrete definition of "interface". This can swing from just a verbal formalization to full-blown first class interface support.
- Different audiences want to see different kinds of interface documentation.
- No process for writing API documentation exists yet (although there is a process in the fish bowl that has very close goals to this).
- API documentation is a very well known pattern, straying from this pattern too much will confuse.
- Writing API documentation is high risk, API docs must be extremely accurate
- API docs are "brittle" in that changes to Zope must be done in a very disciplined way, otherwise API docs become quickly inaccurate and useless (these last two risks are related to Unit Testing, which is outside the scope of this project, but should be considered as a possible "Actor" of API documentation).
- Allowing third party developers to write interface documentation compliant with our goals should not tie the developer to specific policies, for example, they should not need to agree to a "contract" style interface if they wish to provide only documentation on an interface they reserve the right to change, break, or delete, at any time.
- Should an interface be a contract with the user about the behavior of an object? How does being obligated to conform to an interface into perpetuity affect the way interfaces are concieved, documented, extended, and deprecated?
- Trying to solve the problem for Python as well as Zope should absolutely be considered, but may cripple the ability to deliver documentation in a timely manner.
Solution
The solution is documentation for Zope's interfaces. To achieve this goal, a fish-bowl project will be created to determine:
- What is an "interface"
- How interface documentation is authored, reviewed, and maintained
- How to deliver interface documentation (for example, should it all be delivered as a compendium Developer API Reference?).
- How this project should or should not be merged with the OnlineHelpSystem? API reference.
Deliverables
- A definition for "interface"
- A process for authoring, reviewing, and maintaining documentation for an interface.
- Interface documentation artifacts