[Zope] general API question

[Jim Anderson]

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
>
>