Hi Alec,
I think this document is really great, it will be fun to have people try
it out. :)
Minor comments below:
Chandler extensions are usually called 'parcels'.
The schema api and overview docs introduce terminology by bolding it the
first usage, and then using it normally thereafter. Perhaps we should be
consistent across docs?
The Feeds parcel: An RSS Reader
It would be cool to have a screenshot of Chandler with the extension and
some data. The intro is a bit short before jumping into "Starting Chandler".
For normal Python development, you should only need the compressed
"End-Users' Distribution" for your platform.
Are we changing this terminology? (so that parcel developers
don't scratch their heads wondering why they are downloading an
end-user's distribution).
The schema syntax is similar to that used in the Django project.
I agree with Ted about Django. If you do keep in it, perhaps link to the
project. My first reaction was to stop reading the doc and go google it. :)
The Sidebar is a list of Collections.
Agree with Ted that the Collections link isn't very useful, probably
fine to just not link these.
In the simplest case, a FeedChannel is a collection similar to the
All, In, or Out collections. These collections are implemented with
the Collection Kind.
This is the first use of the K-word -- I think you could get away with
saying "Collection class" here, and be more clear. There isn't a real
need to introduce the term "Kind" here.
One small detail here is the key attribute. You'll notice that it
refers to FeedItem.getKind(). Kinds were briefly discussed at the
beginning of this document. Here we use getKind() to get a value that
can be stored in the repository. Like iterItems(), getKind() operates
on a class, so there is no implicit view. The view that is used comes
from the parcel that is being installed.
Back to the K-word. I don't think the tutorial still discusses Kinds
briefly at the beginning -- maybe that got cut. I think its fine to
introduce it late.
The paragraph needs to explain several things:
- what Kinds are (PJE described them in his doc as 'persistent
representations of the schema for one or more Python classes'.)
- that you are getting an object from the repository with
feeds.FeedItem.getKind(parcel.itsView)
- that the view belongs to the parcel being installed (no implicit view)
- that the Kind is used to map the right tree of blocks to the right Item.
Perhaps expand the paragraph to cover each point separately?
Cheers,
Katie
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
