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
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
