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