[ZODB-Dev] We need to pay down debt
Jim Fulton
jim at zope.com
Thu Oct 5 11:05:14 EDT 2006
Dmitry Vasiliev wrote:
> Jim Fulton wrote:
>> 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.)
>
> What do you think about to use an API documentation tool, epydoc
> (http://epydoc.sourceforge.net/) for example? Unfortunately I haven't
> used it myself yet, but the examples looks promising (for example:
> http://epydoc.sourceforge.net/api/epydoc.apidoc.VariableDoc-class.html).
There was an attempt to use it for ZODB that I really didn't like.
It requires too much weird markup that hurts readability in my strongly-
held opinion. This can be mostly mitigated by using a less-intrusive
epydoc-supported format, but I'd really rather see a less formal
mechanism used.
>> Thoughts? Is anyone willing to help out? Anybody interested in a
>> ZODB Doc Day?
>
> I'll ready to help with the docs. I guess we'll can made some minor
> API/code cleanup at the same time. But I think "ZODB Doc Days" is
> unnecessary.
The advantage of the Doc Day, if we can get the right people there
(I'm thinking of Jeremy and Tim :) is that we can discuss questions
about what should go in the API, of which there will be many.
I suppose an alternative would be to do the initial work in a wiki and
ask for comments before committing to the repository.
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
More information about the ZODB-Dev
mailing list