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