I'll provide some time for this, Jim.
I'm no expert on the ZODB, which might be spun as an advantage, and I'm prepared to play a supporting role cleaning up doctests, or helping with doc organization. This means I don't mind gathering spippets from those who have them and pulling them together.
--r

On 5 Oct 2006, at 13:32, Jim Fulton wrote:


I'm happy that there is interest in improving ZODB.  I think, however,
that the most pressing need is for documentation.

When I originally developed the ZODB, I created a UML model:


This provided a fairly thorough and clear documentation of
the ZODB architecture at the time.  It still contains useful information.
Unfortunately, the UML model became corrupted by the tool I was using
and could not be updated. Given advances in our own technologies
since then, I don't think I would use UML today, except perhaps
as a tool for making pictures. (Diagrams can be very useful and
their benefits should not be underestimated.)

We desperately need current and correct documentation of the
ZODB architecture and APIs.  I think that the lack of
clear documentation and specifications severely hampers our
ability to make progress. (It certainly hampers mine.)

ZODB authors were aggressive in creating automated tests for ZODB.
They should be commended for this. These tests, however,
were (mostly) created before we learned how to employ doctests
to create executable documentation and understandable tests.
As a result, the existing tests don't do much to document the system and
make it difficult to deal with tests failures, especially when
refactoring, as it is often difficult to tell what the intent of
failing tests was.

Here's what I'd really like to see soon. I'd like to see us
clearly document our architecture and APIs through:

1. A complete and accurate set of interfaces.

   I made a start at this a few months ago on the jim-dev branch,
   but didn't finish the effort due to uncertainty and other
   priorities.

2. A collection of executable documentation (doctests) focused on
   how to use the APIs, including both static and dynamic behavior.
   The focus of these should be documentation, but the documentation needs
   to be in the form of doctests so we can be fairly sure that the
   documentation is and remains correct.

I think this is an area where a lot of volunteers could make
contributions.  Perhaps we could even schedule some ZODB "Doc days",
similar bug days, but with a different emphasis.

I won't insist that new work should wait for this effort, although
I'd like to. :)  Certainly, I've refrained from pursuing some
ideas of mine in large part because I think we need some foundation work
first.

Thoughts? Is anyone willing to help out?  Anybody interested in a
ZODB Doc Day?

Jim

-- 
Jim Fulton           mailto:[EMAIL PROTECTED]       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org
_______________________________________________
For more information about ZODB, see the ZODB Wiki:

ZODB-Dev mailing list  -  ZODB-Dev@zope.org

Russ Ferriday - Topia Systems - multilingual content management
contact: [EMAIL PROTECTED] - (+44) (0)2076 1777588 - skype: ferriday
a member of the
evenios group

_______________________________________________
For more information about ZODB, see the ZODB Wiki:
http://www.zope.org/Wikis/ZODB/

ZODB-Dev mailing list  -  ZODB-Dev@zope.org
http://mail.zope.org/mailman/listinfo/zodb-dev

Reply via email to