[Dev] CPIA documentation feedback

[Bryan Stearns]

The new documentation looks really good, John... a few comments:

(in BlocksWidgetsEventsCollections...)
- You explain the block-widget relationship in terms of 
model-view-controller, but you don't mention who the controller is. 
Philosophically, I think of the content/domain model (the collection or 
item in your diagram) as the model and the Block as the controller, but 
that's a specific interesting point about our architecture: the block 
has controller- and model-like characteristics. I think this is an 
important thing to make clearer here, since it's novel.

(in IntroductionToBlocks...)
- The first paragraph seems rushed, and introduces a slew of new 
classnames without much supporting info. I don't know whether a picture 
would help here, or just more verbiage, but it seems like that section 
would be clearer if the paragraph were broken into several that each 
introduced a concept: The UI is a hierarchy of blocks with 
parentBlock/childrenBlocks relationships; most blocks are subclasses of 
RectangularChild, which own a chunk of two-dimensional space for their 
children; BoxContainer is a RectangularChild that adds sizing/layout 
behavior; and MainViewRoot's the root of the hierarchy, and it's found 
at startup time.

- The BranchPointBlock introduction starts with the way we use it to 
host the entire UI; developers are more likely to encounter its other 
uses (between sidebar & summary, or summary and detail view) first, then 
maybe note at the end that we use it to host the UI.

- The BranchPointBlock's use of a delegate doesn't seem like part of the 
MVC paradigm, I think it's more accurately the Delegate design pattern.

- When I was new, I found the name 'render' confusing: I'm used to 
thinking of it as the drawing process, not the process of building up a 
structure that'll later be used for drawing. If other folks were also 
confused by this too, it might bear explanation.

- The MainView's Children section could really benefit from that simple 
block diagram that we draw on the whiteboard every time we start talking 
about the UI :-)

- I don't think the comment about ContextMenus & ContextMenuItems being 
"flawed" adds anything at this point in the reader's education.

(in BlockEvents...)
- This document seems out of order... I think the dispatch mechanisms 
discussion could come last... but maybe this document is still a 
work-in-progress (I see that the first two paragraphs have a lot of the 
same text...)

...Bryan


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 
>
> http://wiki.osafoundation.org/bin/view/Projects/IntroductionToBlocks
> http://wiki.osafoundation.org/bin/view/Projects/BlockEvents
>
> I'll have more sections ready for review soon.
>
> Thanks,
> John
>
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>
> Open Source Applications Foundation "Dev" mailing list
> http://lists.osafoundation.org/mailman/listinfo/dev