[Zope] general API question
Paul Winkler
pw_lists at slinkp.com
Tue Sep 28 12:03:59 EDT 2004
Jim has lots of good questions... this is a bit long but
I'm keeping this on-list for anyone else interested in
the API reference update.
On Tue, Sep 28, 2004 at 11:27:07AM -0400, Jim Anderson wrote:
> 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.
you're welcome :) Hope I don't bollox it up too bad :-)
> 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).
That's fine (even ideal) for the API reference.
> 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?
I can only really speak about the Zope Book as that's the only
docs I'm involved in.
The print edition of the Zope Book was planned and executed by
Amos Latteier and Michel Pelletier. Since then, it has evolved quite a
bit. Chris McDonough is more or less in charge of it, but the structure
is not ideal, and it tends to get longer and acquire more redundancy.
What happens is that individual people edit a single chapter and
Chris gives it some sort of overview, but he doesn't make radical
or structural changes to what we send him.
Part of the problem is that Zope is inherently hard to write about:
in order to fully understand topic A, you need to have some understanding
of topic B, which depends on topic C, which depends on a basic
understanding of topic A. We try to address this by having
"basic" and "advanced" chapters on some topics, but I'm not sure
how well this succeeds.
Fixing this would be very hard. One would have to read the entire book
front to back while keeping in mind a newbie's perspective.
I don't know who has time for that :-(
I would do it in a second if somebody would pay me :-\
> - 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.
Not XML, but I do have a long-term proposal for the
API reference:
http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
It attracted some positive comments, but not a groundswell of
support. I'm gonna have to push if I want it to happen.
It's definitely not going to happen before zope 2.8. Maybe for zope 2.9?
This is an even bigger job than just editing the zope book version
of the reference. In the interests of expediency, I decided to
punt and get something online that people can benefit from asap.
(snip)
> 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.
It would be if it were anywhere near complete and up to date :-\
I fear it has suffered some bit-rot.
Fixing (actually replacing) this is part of the above-mentioned proposal.
> - 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.
True. The only "problem" with my proposal is that it would require
zope.org CVS/SVN checkin rights in order to commit changes
to the docs, which raises the bar a bit.
> - 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?
Well, I'm getting more feelers... you're now the third,
and one of the others sounded less experienced than yourself.
There's plenty a relative newbie can do, even just saying things
like "I'm new and from my perspective the XXX example makes no sense
because ...".
> - 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.
There's nothing formal. Generally somebody proposes a project
to update something and people jump on board as able.
I don't know of any current organized efforts wrt. the dev guide.
For the current Zope Book project, see:
http://www.plope.com/Books/zb_signup
> - Is the documentation kept in CVS or some other repository?
The Zope Book nominally lives online at zope.org.
The 2.7 edition is currently at Chris' plope.com site because zope.org
was effectively crippled at the time he wanted to start the project.
There was a sourceforge project for the ZB a long time ago,
but it's years out of date now. I kinda think revision control
would be good for the book but I wasn't willing to put in the effort
to make that happen, and Chris doesn't seem to mind the current
state of affairs, so ... *shrug*
> - 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 did 12 on a day off and it took me 12 hours... *shrug*
OTOH a good chunk of that was spent dealing with DateTime
which is huge.
> 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?
That's fine. Sometimes weeks go by without me touching anything.
We have no deadline.
> - 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.)
I know. I'm having a hard time with this.
But I don't know if you realize quite the magnitude of what
you're suggesting :-) For example, DTMLMethod inherits from something
like 25 classes. I've already punted on a few of the modules
I've overhauled.
The thing is, what we really want to document is not the implementation,
but the interface. Ideally we would have IFoo interfaces for
everything, as described in the SanitizeHelpSysAndAPIReference
wiki. Someday...
> - Do I use Zope 2.7.3 source code for the documentation effort?
Yes. Latest stable or beta.
> - Can I use 'vi' to edit and then merge submit a text file?
Yep. You can get the "source" (structured text) like so:
http://www.plope.com/Books/2_7Edition/AppendixB.stx/document_src
Send me a diff and I'll merge it.
> - How do I know a private from a non-private method? From
> the '_' prefix?
Another topic that should be easier than it is :-\
Anything with a _ prefix SHOULD be private, but OTOH some things
are fairly widely used, such as ObjectManager._setObject
and _getObj. And then there are occasional non-_ methods that
are definitely not API, such as AccessControl.User.UserFolder.hasUsers(),
which at least is documented as not being part of the API.
So you have to make some judgment calls about what
is and isn't API. If unsure, ask this list, or maybe
zope-dev list.
> 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.
Hmm, well 'random' is really just the python standard lib
module so there's nothing to document really, except make sure
the link to python docs is correct.
--
Paul Winkler
http://www.slinkp.com
More information about the Zope
mailing list