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
_______________________________________________
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com

Reply via email to