[Zope3-dev] Re: Big import blocks

[Jim Fulton]

Jeffrey P Shell wrote:
> On Thursday, March 20, 2003, at 09:26  AM, Guido van Rossum wrote:
> 
>> Jim's always on a crusade against "dead chickens" (arbitrary things
>> you have to do before you can do what you want to do).  I'm beginning
>> to count the blocks of "from zope..... import ...." at the top of
>> every Python module a huge dead checken.
> 
> 
> Those big import blocks, and being able to follow them, is the only way 
> one can even figure out Zope 3 right now.  "zapi" is a good idea, but it 
> better be documented extremely well and that documentation better be 
> extremely easy to get to. 

Yup.

 > The only real documentation right now is the
> code,

This isn't really true.  We've written quite a bit of documentation.
Most interfaces have extensive doc strings. There is a growing number of
readme files.  I've put a lot of effort into turorials and white papers.
There are a number of examples.

We've put a lot of effort into documentation and I'd like us to be given
*some* credit for it. :)

Having said that, I realize that much of the documentation isn't easy to
find.  I'd love to get some ideas and help for making documentation
easier to find.


> So all of those 'zapi' things better have real docstrings, so I can at 
> least try to learn them by using help(zapi.getService) in the 
> interpreter without being told "see IGetServices".
> 
> The dead chicken right now is not the amount of imports, it's being able 
> to grasp what you need to do, what you need to import, how things work 
> (enough to feel confidant in doing your own work), and of course, ZCML 
> (I still think most new users will spend more of their time getting 
> comfortable with ZCML than with anything else, at least - based on my 
> own experiences).  I'd rather someone tell me what the ObjectHub is, and 
> when, where, and how to use it, than make it easier for me to import.

In other words, you want some orientation documentation so you know what
details to look for.  I agree that this is needed. The readme files are
a step in this direction.  I like them because they are very simple. It would
be great if folks could help with these and with organizing these. For example,
some orientation readmes telling people where to look based on what they want
to do.

Jim