[Dev] review of BuildingChandlerParcels

Thu Dec 1 10:20:47 PST 2005

Hi Phillippe,

Thanks for your comments.  It's good to get the perspective of  
someone who is relatively "new" -- I certainly can't claim that any  
more.   I plan to incorporate a number of your suggestions into the  
next revision, along with the feedback that I already got from PJE  
and Alec.   This was a minor revisio of the PyCon paper, not a top to  
bottom rewrite.   Also,  I checked my version in before I saw what  
Alec was working on, so there is definitely some coordination that we  
can do there to make things better.

Ted

On Dec 1, 2005, at 1:03 AM, Philippe Bossut wrote:

> 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
>

----
Ted Leung                 Open Source Applications Foundation (OSAF)
PGP Fingerprint: 1003 7870 251F FA71 A59A  CEE3 BEBA 2B87 F5FC 4B42