[Dev] Objection to the new CPIA example

[Phillip J. Eby]

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.

Of course, this probably just means we should be writing developer docs 
much earlier in the release cycle.  :)

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.