Re: [ZODB-Dev] We need to pay down debt
Jim Fulton wrote at 2006-10-5 08:32 -0400: ... 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 Good! although I'd like to. :) Sad. Certainly, I've refrained from pursuing some ideas of mine in large part because I think we need some foundation work first. Thoughts? I am ready to write doctests for new features I develop (although I like unit tests much more). I am not inclined to work on documentation primarily. -- Dieter ___ 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
Re: [ZODB-Dev] We need to pay down debt
Russ Ferriday wrote at 2006-10-5 13:45 +0100: 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. If you have questions I will try to provide answers :-) -- Dieter ___ 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
Re: [ZODB-Dev] We need to pay down debt
Jim Fulton wrote at 2006-10-5 08:50 -0400: Russ Ferriday wrote: 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. Awesome. Perhaps you can start thinking about how to organize the doctests. I think that there are 2 (or 3) main audiences to consider: - Users of ZODB These folks need guidance on how to use ZODB to develop applications, including pitfalls. I do not think that doctests are the optimal means for those target group. A guide, such as Andrew's guide, seems more appropriate in my view. -- Dieter ___ 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
Re: [ZODB-Dev] We need to pay down debt
Jim Fulton wrote: Dmitry Vasiliev wrote: Jim Fulton wrote: 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. It's cool, but it's hard for me to follow the days because of the time zone differences. :-( I suppose an alternative would be to do the initial work in a wiki and ask for comments before committing to the repository. +1 I can draw UML class diagrams for ZODB with Dia (http://www.gnome.org/projects/dia/) and place it in the repository (as .dia and .png files) so we can have an overview of the current implementation. -- Dmitry Vasiliev (dima at hlabs.spb.ru) http://hlabs.spb.ru ___ 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
Re: [ZODB-Dev] We need to pay down debt
On Oct 5, 2006, at 9:37 AM, Jim Fulton wrote: Russ Ferriday wrote: Do you have some favorite documents that you would point me to as most accurate or up to date? No, because I haven't used ZODB documentation much myself. :) Decent clues will be enough to get started. - Doc in test or source files - web pages, - forums chats, - email threads The ZODB wiki which is here, in case you didn't know http://www.zope.org/Wikis/ZODB/FrontPage (or Google for ZODB wiki - I'm feeling lucky ;-) has some pointers In particular, I usually point people here (which is a link from the wiki): http://www.zope.org/Wikis/ZODB/FrontPage/guide/index.html Gary ___ 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
Re: [ZODB-Dev] We need to pay down debt
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:[EMAIL PROTECTED] Python Powered! CTO (540) 361-1714http://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@zope.org http://mail.zope.org/mailman/listinfo/zodb-dev
