On Nov 7, 2005, at 12:53 PM, Phillip J. Eby wrote:
At 11:34 AM 11/7/2005 -0800, Philippe Bossut wrote:
I'm a little bit more concerned though by the changes to chandler/
parcels/osaf/ files included with that commit. I'm reluctant to
see any kind of modification at that point of the release cycle
for the unique incentive of writing example code and doc. Only bug
fixes should be allowed there.
At the same time, by *not* allowing changes to result from writing
example code and documentation, we prevent feedback from the
documentation process entering the design. My experience many,
many times has been that when I go to write developer documentation
for a feature, that is when I discover that the feature is hard to
sensibly explain to an outsider. This then forces me to think of
how to make the feature inherently more explainable, and therefore
how the feature should best be designed for understandability and
ease-of-use.
You are restating a principle that I've been hearing from Katie,
usually with regard to the end user API, namely "You are not your own
user". This is also true when you are developing something like the
parcel API's. The question is when is the right time in the
development cycle to act on feedback. For better or worse, I think
that it's a little late for changes like this . If the code in
question really was a better way of handling the general case instead
of simplifying a special case, then the checkin should have included
a rewrite of all the example parcels in order to demonstrate
preferred practice.
Of course, this probably just means we should be writing developer
docs much earlier in the release cycle. :)
Either that or have shorter release cycles to shorten the feedback
loop. But that's problematic for other reasons.
Full disclosure: I proposed the specific details of the
ViewableKind mechanism to John in response to a series of questions
he had about various ways of implementing the same idea with the
schema API. I believe our initial discussion took place before the
feature freeze, however, and I'm not really "in the loop" of
current CPIA design/planning I was under the impression that it was
for a feature that was officially planned for 0.6.
Mainly, I was trying to provide John with the best that the schema
API had to offer in implementing the mechanism he desired, and
since the idea he presented sounded to me like a mechanism that
would be easy to explain and use, I had no reason to look beyond
the boundaries of helping him accomplish this expressed goal.
I'm not very familiar with the API it's competing with, though, so
I have no opinion on the relative merits, and I also don't support
having two APIs. If an API is hard we should make it easier,
rather than have separate easy and hard APIs. Obviously, however,
it's too late for API changes in 0.6, even if some kind of change
were merited.
It is very easy for each of us to look at our own piece of the system
in isolation, and do what is good for that single part. It is much
harder to look at the entire system as a whole and figure out what
the right thing to do. I'm nervous that we are producing lots of
local maximums which lead to global mediocrity.
Ted
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
