[Dev] CPIA documentation feedback

[Philippe Bossut]

Hi John,

Thanks for putting those docs together. I think it's a good start in 
documenting CPIA.

Like Ted, I  feel that some explanation of the goal of the design would 
help. Most of the design will not be foreign to developers who are 
already familiar with UI frameworks but for the others, it's a little 
challenging to get into it.

Also, more graphics explaining the relationship between the different 
concepts will help greatly.

Last, (and this is a general comment I make every time I review 
documentation), try to avoid long paragraphs rambling over 10 lines, 
addressing 2 or 3 concepts at once then an example of something else to 
glue everything into a long narrative. It's hard to read, prevents speed 
reading and make quick glances for reference impossible.

For technical docs, cut the literature and stick to simple writing 
rules. I posted something on this some months ago here:
    
http://wiki.osafoundation.org/pub/Journal/PhilippeBossutNotes/GeorgesSieve.htm

More detailed feedback here under.

Cheers,
- Philippe

John Anderson wrote:
> http://wiki.osafoundation.org/bin/view/Projects/BlocksWidgetsEventsCollections 
>
I was quite confused by the order of things in this document and the 
layout of paragraphs. You can't put in the title that "Collection" is a 
key concept and introduce this key concept through an example within the 
"Block" paragraph (another key concept). It's impossible to articulate 
the 4 concepts without deconstructing the whole document. Extremely 
confusing.

I actually went ahead and edited the Wiki page to give a little bit of 
air and structure to the presentation (don't worry, it's the same 
sentences but in a different order).

Other than that, it's a good concise intro to the subject.
> http://wiki.osafoundation.org/bin/view/Projects/IntroductionToBlocks
Same as above as far as document structure is concerned.

Puzzling sentence 1: "Rendering adds the widget attribute to the block 
that points to the widget and the blockItem attribute to the Block, that 
points to the widget".
So they both point to the widget? but one is added to the "block" and 
the other to the "Block"? What's the difference between a capitalized 
Block and a non-capitalized block? Is that call / instance difference?

Puzzling sentence 2 : "If the Block has contents, it is subscribed to be 
notified of changes to the contents."
Who or what is subscribing to the Block? Isn't that the Block which 
subscribes to its content?
> http://wiki.osafoundation.org/bin/view/Projects/BlockEvents
Ditto for structure.

It would be good to have an explanation of what the fundamental dispatch 
mechanism is. The doc dives directly into the various dispatch enum but 
without a clear understanding of how dispatch works there's a gap in the 
reader's understanding.

A simple graph here showing Blocks and BlockEvent and how dispatch works 
would certainly help.

Cheers
- Philippe