[ZODB-Dev] We need to pay down debt

[Russ Ferriday]

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:
>
>   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
> _______________________________________________
> For more information about ZODB, see the ZODB Wiki:
> http://www.zope.org/Wikis/ZODB/
>
> ZODB-Dev mailing list  -  ZODB-Dev at zope.org
> http://mail.zope.org/mailman/listinfo/zodb-dev

Russ Ferriday - Topia Systems - multilingual content management
contact: russf at topia.com - (+44) (0)2076 1777588 - skype: ferriday
a member of the
evenios group

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.zope.org/pipermail/zodb-dev/attachments/20061005/36b390e3/attachment-0001.htm