[Zope3-dev] Re: Zope 3 as a reliable platform?!?

[Philipp von Weitershausen]

Christian Theune wrote:
> I partially agree on that. This obviously is one issue if you're living
> on the trunk or a pre-release branch. It's not clear when to re-read, so
> following the checkins is required here.

Yup. But as you said, that's because you're living on the edge.

>>> That's probably my fault because I didn't digg deep enough to
>>> verify the truth whether zope.component.provideUtility works against the
>>> thread local component registry or not.
>> Dig deep enough? How about digging ALL THE WAY (sorry, being ironic
>> here) to zope.component.interfaces and reading the declaration of
>> provideUtility:
>>
>>     def provideUtility(component, provides=None, name=u''):
>>         """Register a utility globally
>>     ...
> 
> Again, you're right. The information is there, but I didn't *expect*
> that the docstring contains any important information (for me at this
> point in time and when I was looking for the correct signature of the
> method). If had expected that change, I would probably have read the
> docstring.

What are you saying here? You don't expect interfaces to "contain any 
important information"? I hope I'm misunderstand you here... In fact, I 
think I am because I don't really understand what you're trying to say 
with this paragraph ;).

>> How is that not clear? If you don't read interfaces for what we provide
>> them (declarative documentation), then I'm running out of ideas on how
>> to satisfy you.
> 
> I read them. This is a bit of psychology turning against me here, I was
> looking at the line above, but failed to read the line below because my
> expectation didn't include that the docstring has any additional
> information to what I was looking for.

Sigh, if only we could make things appear in red :).

Seriously, you said you were looking at the method signature but 
complaining you had to dig deep to find out about the function's 
behaviour... That seems totally unreasonable to me.

By the way, a lot of time we have to rely on docstrings to document 
behaviour. Let's take

   class IAttributeAnnotatable(IAnnotatable):
       ...

Without a docstring, this teeny-weeny declaration is absolutely meaningless.

>>> What I'm worried about is that we have to come up with a *MUCH* better
>>> way to tell people "What is *the single* way to do this or that?" and
>>> "Hey, we used to do it *this* way, but HEADSUP, now it's *that* way!".
>> I'd welcome any constructive suggestions. I, for one, suggested a
>> "What's new in Zope 3.X" article.  Baiju M started such an article
>> (google it) and I contributed a few things here and there to it. (Thanks
>> to Baiju, btw!!!)
> 
> Ah. I think I saw that on the list once as a work in progress or
> proposal. I hadn't had time back than to look into this. I just found
> the URL and skimmed over it. I think this is probably exactly what I
> would love to see for major releases. I think I'll start translating
> that to german until the final release of 3.3.

Perhaps we should get the English version up to shape first. I don't 
think it's completely finished yet.

> Those things deserver a lot more visibility than they get right now.

I agree.

> Hopefully the new zope.org website will handle that.

I've volunteered to look into that. And I agree.

>>> Again, maybe I'm only hitting this all the time because I'm living most
>>> of my live on pre-release-branches or the trunk, but still.
>>>
>>> I think if Zope 3 shall be used by many people, this is a major obstacle.
>> Whether it's many or just few people... RTFMing is all it takes for them
>> to get started. I've written a whole friggen book for them, for cryin'
>> out loud :)
> 
> Sure, but that doesn't hold up for 3.3

Hey, unfair! I'm working on a 2nd edition!

> Additionally RTFMing with Zope is hard because:
> 
> - - there is no TFM

APIDoc can be considered *a* FM.  It includes all the major .txt files 
and you can browse APIs and look at docstrings. I think that's pretty 
darn good.

> - - I (and I think quite some other people too) don't even have the
> expectation anymore to find something in the FM because e.g. "The Zope
> book" had only two or three sentences that I came back to (via google)
> for references and was always barely up to date.

That's a historical problem that we can't do anything about except 
improve in the future. I think we already have improved, but we can't 
rewire people's heads.

Your brain seems to be wired a lot towards Zope 2 and its bad state of 
documentation :).

> - - When I don't know that something changed or is different than I think
> (and it doesn't seem to behave wrong in the first place) I don't start
> looking into the code.

And you shouldn't have to. Remember the other day when you barfed at me 
about the <vocabulary /> directive gone? You barfed at me without even 
having googled the proposal. I'm sure you could've found it easily.

> Again, I agree that I could be much more on the hook if I
> 
> - - read all proposals
> - - read all checkins
> - - follow and participate in all zope3-dev discussions

That is probably only necessary if you're running bleeding edge (then 
again, you *are* doing that, so you shouldn't complain).

> So, I agree that "normal" developers might not have the same problem as
> I do, because they get the benefit of having a fixed point in time where
> they get the release and then just read the change log and can be happy.

Yes.

> Then it only imposes a problem for me and maybe other people who want to
> contribute to Zope and work on and with the pre-releases and trunk. This
> is a much smaller focus group, but it's also a very important one,
> because we really could do with more people contributing.
> 
> And if more people would be contributing the situation might get worse
> because I would miss even more stuff.
> 
> I wonder whether I'm the only one who feels like it's hard to keep up?
> 
>>> I hope I don't annoy anybody, but I had to get that off my mind.
>> Sure. Grab a cool beer, cool off and start improving the situation
>> tomorrow (and tell me how so I can do it in the future too) :)
> 
> I'll stick with some non-alcoholics, but I'm trying to cool down,
> rationalize and provide constructive thoughts.

That'd be great. Have a nice evening :)

Philipp