[Dev] Objection to the new CPIA example

[Ted Leung]

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