Paul, First, thank you for taking on a big responsibility. That is my personal thanks, but I think the entire Zope community owes you a thanks. As a bare minimum, I would like to volunteer for one module. Hopefully more, but let's see how it goes. I have considerable experience as a programmer in C, and some in C++ and Python. I have also done my share of documentation in my time and I can write OK, but tend to be boring in my writing (typical engineer). I do have a number of comments/questions about Zope documentation in general: - As a user, I find the documentation quite useful, but not well structured compared to other documentation projects that I have seen. It leads me to wonder if any one group of people are responsible for planning the overall documentation, or did it just evolve? - What comes to mind about the API documentation is my surprise that it is included in the Zope Book in the first place. As a user, I'm much happier using a UNIX manual page or the python html reference information. Has any thought been given to taking the API out of the Zope book and making a stand alone version in XML. Ideally, this API should be available online, but also easily printable so I can put a ZOPE API reference on my book shelf. My experience is that I use online documentation much more, and more efficiently, but sometimes it is tough to beat thumbing through a hard copy. To be honest, I have not used the HelpSys in Zope and maybe this is what I'm looking for with respect to online help. - My opinion is that if reference material is more modular, then the documentation will never be up to date - but, it will evolve more quickly, especially since developers can then update documentations in small increments. - I'm not too experienced in Zope and I'm afraid I will need support in my effort to provide documentation. I think the need for support will diminish as I come up to speed. I wonder how many others out there think of volunteering, but don't because they don't feel they can contribute? It would be interesting to see the existing Zope community be more 'newbie friendly' and to let the newbies know that they are welcome and will be supported as they make their contributions. Personally, I have gotten so much out of Zope already, that I feel obligated to put something back in to it. - I assume there is a group of people to help with the documentation? How big is the group? How is it structured? Is there a group that works on the Zope Book and another that works on the Developers Guide, which I believe needs updating even more than the Zope Book. - Is the documentation kept in CVS or some other repository? - What is the time frame for reviewing a module? I know you said it takes you an hour to do a good job on a module. I suspect it will take me 10 times that on my first module because I'll have questions about it. If I commit to have it done in 10 calendar days, is that all right? - The base class documentation needs to be consistent. In my opinion, all (public) base classes need to be documented individual in the API and reference in derived classes. The last thing you want to do is document base class methods in each derived class (what a mess that would be.) - Speaking of classes, I would really like to see some kind of URL document for Zope included in the developers guide (different topic I guess - sorry) - Do I use Zope 2.7.3 source code for the documentation effort? - Can I use 'vi' to edit and then merge submit a text file? - How do I know a private from a non-private method? From the '_' prefix? With the questions/comments behind me, I'm willing to take a shot at the 'random' module, trying to choose a simple module to start with. Let me know if you would like me to start on it. Regards, Jim Paul Winkler wrote:
On Sun, Sep 26, 2004 at 03:57:49PM -0400, David Evans wrote:
is there a more complete API reference available, and if not how can i contribute to the update of the curent API to a more complete status?
I've volunteered as editor of the API reference for the next (2.7) edition of the Zope Book. Help would be greatly appreciated.
The version I'm working on is here: http://www.plope.com/Books/2_7Edition/AppendixB.stx
Note the current TODO list here: http://www.plope.com/Books/2_7Edition/AppendixB.stx#1-2
Currently what I'm doing is the first item on that list. A BIG help would be to take responsibility for one or more remaining modules on the list below.
* For all modules, classes, methods, and functions in the reference:
* verify that all names are correct
* see if any non-private methods are missing, and add them
* compare API reference to source docstrings and to the HelpSys .stx files, combine and edit all for completeness and clarity.
* check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
It's a big job, best done one module at a time. So far it takes me about an hour to do one module properly :-( Some modules are done, see DONE below.
The below modules are still to do::
PropertySheet PropertySheets PythonScripts Script SessionInterfaces TransienceInterfaces UserFolder Vocabulary ZCatalog ZSQLMethod ZTUtils math random sequence standard string