<HTML><BODY style="word-wrap: break-word; -khtml-nbsp-mode: space; -khtml-line-break: after-white-space; ">I'll provide some time for this, Jim.<DIV>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.</DIV><DIV>--r</DIV><DIV><BR><DIV><DIV>On 5 Oct 2006, at 13:32, Jim Fulton wrote:</DIV><BR class="Apple-interchange-newline"><BLOCKQUOTE type="cite"><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I'm happy that there is interest in improving ZODB.<SPAN class="Apple-converted-space"> </SPAN>I think, however,</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">that the most pressing need is for documentation.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">When I originally developed the ZODB, I created a UML model:</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN><A href="http://www.zope.org/Documentation/Developer/Models/ZODB">http://www.zope.org/Documentation/Developer/Models/ZODB</A></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">This provided a fairly thorough and clear documentation of</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">the ZODB architecture at the time.<SPAN class="Apple-converted-space"> </SPAN>It still contains useful information.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Unfortunately, the UML model became corrupted by the tool I was using</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">and could not be updated. Given advances in our own technologies</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">since then, I don't think I would use UML today, except perhaps</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">as a tool for making pictures. (Diagrams can be very useful and</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">their benefits should not be underestimated.)</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">We desperately need current and correct documentation of the</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ZODB architecture and APIs.<SPAN class="Apple-converted-space"> </SPAN>I think that the lack of</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">clear documentation and specifications severely hampers our</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ability to make progress. (It certainly hampers mine.)</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ZODB authors were aggressive in creating automated tests for ZODB.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">They should be commended for this. These tests, however,</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">were (mostly) created before we learned how to employ doctests</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">to create executable documentation and understandable tests.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">As a result, the existing tests don't do much to document the system and</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">make it difficult to deal with tests failures, especially when</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">refactoring, as it is often difficult to tell what the intent of</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">failing tests was.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Here's what I'd really like to see soon. I'd like to see us</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">clearly document our architecture and APIs through:</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">1. A complete and accurate set of interfaces.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>I made a start at this a few months ago on the jim-dev branch,</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>but didn't finish the effort due to uncertainty and other</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>priorities.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">2. A collection of executable documentation (doctests) focused on</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>how to use the APIs, including both static and dynamic behavior.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>The focus of these should be documentation, but the documentation needs</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>to be in the form of doctests so we can be fairly sure that the</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>documentation is and remains correct.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I think this is an area where a lot of volunteers could make</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">contributions.<SPAN class="Apple-converted-space"> </SPAN>Perhaps we could even schedule some ZODB "Doc days",</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">similar bug days, but with a different emphasis.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I won't insist that new work should wait for this effort, although</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I'd like to. :)<SPAN class="Apple-converted-space"> </SPAN>Certainly, I've refrained from pursuing some</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ideas of mine in large part because I think we need some foundation work</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">first.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Thoughts? Is anyone willing to help out?<SPAN class="Apple-converted-space"> </SPAN>Anybody interested in a</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ZODB Doc Day?</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Jim</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">--<SPAN class="Apple-converted-space"> </SPAN></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Jim Fulton <SPAN class="Apple-converted-space"> </SPAN><A href="mailto:jim@zope.com">mailto:jim@zope.com</A> <SPAN class="Apple-converted-space"> </SPAN>Python Powered!</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">CTO<SPAN class="Apple-converted-space"> </SPAN>(540) 361-1714<SPAN class="Apple-converted-space"> </SPAN><A href="http://www.python.org">http://www.python.org</A></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Zope Corporation <SPAN class="Apple-converted-space"> </SPAN><A href="http://www.zope.com">http://www.zope.com</A> <SPAN class="Apple-converted-space"> </SPAN><A href="http://www.zope.org">http://www.zope.org</A></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">_______________________________________________</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">For more information about ZODB, see the ZODB Wiki:</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><A href="http://www.zope.org/Wikis/ZODB/">http://www.zope.org/Wikis/ZODB/</A></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">ZODB-Dev mailing list<SPAN class="Apple-converted-space"> </SPAN>-<SPAN class="Apple-converted-space"> </SPAN><A href="mailto:ZODB-Dev@zope.org">ZODB-Dev@zope.org</A></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><A href="http://mail.zope.org/mailman/listinfo/zodb-dev">http://mail.zope.org/mailman/listinfo/zodb-dev</A></DIV> </BLOCKQUOTE></DIV><BR><DIV> <DIV id="sig" style="line-height: 13px; margin: 6px 0; padding: 8px; border-top: 1px #BBBBBB solid; border-bottom: 1px #BBBBBB solid; font-family: Verdana,Arial,Helvetica,sans-serif; font-weight: bold; font-size: 11px; color: black; "> <DIV style="float:left; padding: 0px 12px;"> <STRONG style="">Russ Ferriday</STRONG> - <A href="http://topia.com" title="visit topia.com" style="text-decoration: none;color: black;">Topia Systems - multilingual content management </A><BR> contact: <A href="mailto:russf@topia.com" style="color: black; text-decoration: none; ">russf@topia.com</A> - (+44) (0)2076 1777588 - skype: ferriday </DIV> <DIV style="float:left; border-left: 1px solid #BBBBBB;padding: 0px 12px;"> a member of the<BR> <A href="http://evenios.com" title="visit evenios.com" style="text-decoration: none;color: black;">evenios group</A> </DIV> <DIV style="clear:both"> </DIV></DIV> </DIV><BR></DIV></BODY></HTML>