Re: I-D ACTION:draft-ietf-atompub-protocol-14.txt

[Eric Scheid <eric.scheid@xxxxxxxxxxxxxxx>]

On 3/8/07 11:37 AM, "Brendan Taylor" <whateley@xxxxxxxxx> wrote:

>> Section 4, para 3 ('The Atom Protocol only covers...') talks about
>> entry and media resources, [...] Member Resources, Collection
>> Resources, Collections, and a Collection's Member Resources [...]
>> what a service document *is*.
> 
> All these terms are defined in Section 3, Terminology.

I can see how this could still be a bit opaque to someone that hasn't been
on this list all this time. Certainly. referring to Section 3 (Terminology)
doesn't appear to be that helpful ... referring to Section 4 (Protocol
Model) might do the trick though.

(btw, I know Alex, and can vouch for his clue quotient. The fact the spec
presents challenges to him is worrying)


Some nits...

from Section 3. Terminology:

> Entry Resource - Member Resources of a Collection that are represented using
> the "application/atom+xml" media type.

> Media Resource - Member Resources of a Collection that are represented with a
> media type other than "application/atom+xml".

do we want to change these to "application/atom+xml;type=entry"?

-----------

> Collection - A resource that contains a set of Member Entries. See Section 9.

where is the term "Member Entries" defined? Not in Section 3, Terminology.
Is it defined under another name?

-----------

> Member - A resource whose IRI is listed in a Collection by a link element with
> a relation of "edit" or "edit-media". See Section 9.1. The protocol defines
> two kinds of Members - Entry and Media resources.

s/Entry and Media resources/Entry Resource, and Media Resource/

ie. make an unambiguous connection to the two definitions which follow

------------

from Section 4. Protocol Model:

The ordering of the paragraphs of this section appears to me as rather
jumbled: the paragraph discussing URIs and IRIs is between a paragraph
describing Collections and the two flavours of Member Resources, for
example.

Say we number the existing paragraphs as follows:

[1] The Atom Publishing Protocol uses ...
[2] The Atom Protocol does not specify the form of the URIs ...
[3] The Atom Protocol only covers the creation, update and deletion ...
[4] Since all aspects of client-server interaction ...
[5] Along with operations on Member Resources ...
[6] Atom Protocol documents allow the use of IRIs ...
[7] There are two kinds of Member Resources ...
[8] A Collection Feed's Atom Entries ...
[9] Service Documents represent ...

These paragraphs are a jumbled mix of data model, operations, and underlying
mechanisms, and it might be helpful to arrange them into that general order
(starting from most abstract, leading to most specific), then tweaking the
prose to suit:

[5] (about collections)
[8] (what collections contain)
[7] (about members)
[9] (about Service Documents)

[3] (operations, and what they affect)
[1] (operations defined with HTTP)

[4] (refer HTTP spec)
[2] (about URI space and representations)
[6] (about URIs vs IRIs)


e.