[Dev] review of BuildingChandlerParcels

[Philippe Bossut]

Hi Ted,

First, thanks for the update. The disappearance of the parcel.xml stuff 
makes for a much nicer and clearer read for sure... :)

There are still things that are hard to decipher though. As a lay person 
who hasn't developed a parcel yet, I found some paragraphs hard to 
follow. I've been helped of course by my familiarity with the concepts 
described but I think that it's going to be pretty hard for a newcomer 
to grasp everything. Also, it's almost impossible to follow the code 
snippet without the real code at hand. There's too much or not enough of 
it. For sure, everything that is in the doc should be commented and 
explained. If too far fetched or distracting, it should be simply eluded.

Also, some fundamental aspects should have their own paragraph. As a 
parcel reader, I'm expecting to see a paragraph on creating a Kind then 
one on creating Items very clearly identified. The instantiation of a 
FeedChannel item for instance is buried into the "creating a Menu 
handler" paragraph. That's not where I was expecting it.

Somewhat, I'm wondering if the RSS feed is too difficult of an example 
to use in a Building Parcel documentation. Something that would be more 
static may be (read info in some local file store) would be easier to 
present in extenso and avoid some complexity like threading.

On the good side though, I did learn something reading this doc and I 
think I'm ready to code my first parcel. That's very positive... :)

I also read Alec's doc on Zaobao. It's not finished but I liked its 
style better. I appreciated that all cryptic references to Chandler's 
data (pim, schema.ns) are introduced and explained as they appear in the 
code. It makes the writing of a parcel more approachable. The only 
comments I would have on Alec's doc are grammatical in nature and I 
guess I should simply pick it up and commit changes rather than annoy 
everyone with my comments... :)

Back to the BuildingChandlerParcel doc though, here are the notes I took 
while reading:

- Overview
One should mention that Items are not "owned" by Item Collections and 
can appear in several Item Collections as soon as those concepts are 
introduced. Readers might draw false analogies otherwise (like 
collections are folders...) and build faulty mental models.

- 1. Extending Chandler's Schema
I agree with Alec that making the code more dense (less than 1 screen) 
will help readability. There are important info before and after the 
code snippet and I found myself scrolling up and down to try to make 
sense of the context and the example.
Also, I find the sentence "an Item is just a bunch of Attributes" 
confusing. Especially since the next sentence says that Items have a 
Kind which, somewhat, contradicts the first understanding that items are 
free form groups of attributes. It feels like saying that "a Tree is 
just a bunch of Leaves" but that, really there's a structural difference 
between a Kind "Tree" and a Kind "Heap of fallen leaves" but that, as a 
reader, I'm supposed to know that... It sounds like the first statement 
was not really serious and that some knowledge of what Kinds are is assumed.
I think it would be more clear saying that Items all need to have a Kind 
and that before feeding new data to Chandler, we need to define what the 
Kind of these new data is.
The SuperKind explanation is also confusing. One paragraph says that 
"FeedChannel derives from ListCollection kind" (ok...), a later one says 
that "Feed Item has a SuperKind called ListCollection"... Wait, isn't 
that FeedChannel? I can't find ListCollection anywhere in the code of 
FeedItem... Typo? Hidden assumption?
What's wrong with saying that a Kind can derive from another Kind and 
that all Kinds create a hierarchy with ContentItem at the root? Why use 
the subjonctive "should be used as a root"? Is that it's not really 
true? Are there exceptions?
After reading this first paragraph, my mental model is that:
- Kinds are defined like Python classes complete with attributes and methods
- Items are instances of a particular Kind
- SuperKinds... well... looks like they're just Kinds
This model seems consistent with everything I just read but, if it's 
that simple, why not say so? Obviously, I'm missing something but what?
The rest of the doc seems to proove I'm not mistaken but then, this 
section doesn't make things clear enough. Since readers must be Python 
developers, why not use Python analogies early on so that readers can 
trust their mental model? The analogy between Kind (Python class) and 
Item (Python instances) is only made in the last paragraph of the doc. 
Why wait so long?

2. Periodically getting new RSS items.
The introduction of PeriodicTask is nice but feels intimidating: looks 
like it's just the tip of an iceberg of some fundamental part of 
Chandler that we, as first time parcel writer, we better not look too 
deeply in...
The "behind the scene" paragraph reinforce that impression, especially 
starting with the first mention ever of wxWidgets ("what's that?" will 
certainly be the immediate first time reader's reaction) as if it was 
the main impetus behind suporting threads.
Strangely enough, this section can be better understood reading it 
backwards: from Repository to threads then GUI thread then wxWidgets. 
Starting with wxWidgets as the first word to explain Chandler's 
threading system seems wrong.

3. Creating a menu item
The text sort of gloss over creating an item ("like all the other Items 
we've seen so far") but the only other item created in the doc (so far) 
is a PeriodicTask and in a sort of tangential way. The rest were Kinds. 
I feel the doc should explain a little how an item (an instance of a 
Kind) is created, what it means for the repository, etc... soon after 
Kinds are created. The update() method deserves more than a passing 
mention in the context of the creation of the PeriodicTask.
The event item and how events are dispatched is sort of hocus-pocus. Why 
is FeedController invoked? Is feed_controller and instance of 
FeedController? Frankly, the only way to understand this paragraph is to 
open ./parcels/feeds/blocks.py and peer into the code. There's not 
enough stuff or too much.
The "Behind the scene: CPIA" paragraph is hard to grasp. I understand it 
because I've been exposed to the concepts long enough but I really doubt 
that a newcomer to Chandler will understand any of it. It's mind 
boggling. That being said, it's a tour de force of density of 
information: every single word count in there... :)

Installing an Item Detail View
This is code heavy and most of it must be simply trusted by the reader. 
Obviously, there should be a place where the list of available widget is 
provided. A link to such list would be welcomed here.

Where Chandler is today
The doc says we just learn to populate the repository with new data but, 
actually, we haven't done that explicitely. The FeedItem Kind has been 
defined but nowhere is a FeedItem Item instantiated. This is done in the 
Update() method but, here again, short of checking the 
./parcels/feeds/channels.py code, it's hard to follow reading the doc.

Cheers,
- Philippe

Ted Leung wrote:

> Hi,
>
> Building Chandler Parcels <http://svn.osafoundation.org/chandler/ 
> branches/Chandler_0.6/chandler/distrib/docs/ 
> BuildingChandlerParcels.html> is a revision of this year's PyCon  
> paper <http://wiki.osafoundation.org/bin/view/Documentation/ 
> BuildingChandlerParcels> to reflect all the changes that we've made  
> in 0.6.   The goal of the document is not to be a detail tutorial on  
> how to write a parcel, but to present enough detail so that someone  
> has a general idea of the process.
>
> I'd love it if a few people could take some time to review it and  
> suggest improvements.
>
> Ted
>
>
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>
> Open Source Applications Foundation "Dev" mailing list
> http://lists.osafoundation.org/mailman/listinfo/dev