[Dev] CPIA documentation feedback

[Ted Leung]

I'm just getting to these now...

On Jan 15, 2006, at 3:43 PM, John Anderson wrote:

> Hi:
>
> I have drafts of 3 sections of the CPIA documentation ready for  
> review and I'd appreciate your feedback:
>
> http://wiki.osafoundation.org/bin/view/Projects/ 
> BlocksWidgetsEventsCollections

This is a good introduction to "who does what job".  Explaining this  
by relating it to MVC was helpful.   One question that I have, and  
that experienced readers are likely to have is: "what's the benefit  
of using this variant of MVC as opposed to using a more traditional  
MVC model"?    Some explanation of that rationale would be helpful.

> http://wiki.osafoundation.org/bin/view/Projects/IntroductionToBlocks

A lot of this explanation would be easier if there were a diagram  
showing the Chandler UI and overlaying the block structure used for  
each part of the UI.

> http://wiki.osafoundation.org/bin/view/Projects/BlockEvents
>

The section on Dispatching FocusBubbleUp needs a little more context/ 
motivation.  I can follow how it works, but I don't have a good sense  
for why this is designed the way it is.  I'm sure that's just me  
missing something, but I think that some additional background would  
be helpful.

 From reading the section on Event Boundaries and Broadcast Dispatch,  
it looks like this mechanism is there mostly for performance reasons,  
limiting the parts of the tree of blocks that need to handle  
particular events.  Is that right, or am I missing something?

With all three documents, I have a better sense of how it works, but  
not really a sense of why it works the way that it does, and I'm not  
sure that I could, say, build my own block after reading this  
material (I don't know if that was your goal or not)

Thanks for working on these -- I know that documentation is a tough  
task.

Ted