[ZODB-Dev] We need to pay down debt

[Jim Fulton]

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:

   http://www.zope.org/Documentation/Developer/Models/ZODB

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:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org