There's been a good bit of discussion about Zope documentation on the list recently, and improved documentation of the core Zope distribution would certainly be a great thing. However, part of the attraction of Zope are the available extensions in the form of Zope Products. Documentation for these is also important, whether they're being used as is or as a basis for customization, but it's very difficult for these authors to commit the time required to create separate docs. As a result, it's difficult to figure out the structure and workings of most Products. To make Product documentation easier, I propose the following: When a product is installed, there should be a standard mechanism that creates a "Doc" tab with a page containing information compiled from the Product distribution. The first element on the doc page should be a brief overview of the Product, which would be taken from a text or html file in the product directory with a standard name (docs!.html or docs!.doc, for example). The second element should be a listing by name of all dtml pages and methods in the Product with brief explanatory text. The text should be derived from the contents of a dtml tag in each page that functions like a doc string (perhaps a <dtml-doc> tag). The third and last element should be a listing by name of all python modules in the Product with each name followed by the doc string of the module. Indented under each module should be a listing of all callable top level functions in the module with the corresponding doc strings and all classes with their doc strings. Indented under each class should be all callable functions within the class, with their doc strings. Thus at import, the names and doc strings of the elements of the Product would be extracted and collected into a doc page with this organization: Brief description (from file) DTML Page(s) -- each with "dtml doc string" DTML Method(s) -- each with "dtml doc string" FirstPythonModuleName -- doc string Func def 1 -- doc string Func def 2 -- doc string Class def 1 -- doc string Class func 1 -- doc string Class def 2 -- doc string SecondPythonModuleName -- doc string etc. This approach to documentation has the advantage of exposing the overall structure of a Product in addition to documenting its internals. Having the documentation method use doc strings makes it easier to maintain brief but useful documentation and keep that documentation up to date as code is revised. Of course there would need to be some guidelines about how to set up the doc strings (the standard python format would be a decent start) and conventions such as showing what imports what in module doc strings might be helpful. I got started thinking about this when I was trying to customize Squishdot in some fairly simple ways, but ended up having to bother the author (who was very helpful) about where certain functionality was located. While the approach I suggest here doesn't completely take the place of well-written standalone documentation, it could provide a lot of information with substantially less effort, is easier to maintain in the setting of iterative code development, and is consistent with the open source concept of multiple authors extending code's functionality. Jim Harrison ________________________________________________________________________ James H. Harrison, Jr., MD, PhD University of Pittsburgh Health System C920 PUH, 200 Lothrop Street Pittsburgh, PA 15213 jhrsn@pop.pitt.edu | voice: 412-647-5529 | fax: 412-647-9588 "If you want sense, you'll have to make it yourself!!"-Norton Juster ________________________________________________________________________