[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [xri] Pre-draft of "HTTP-based Resource Descriptor Discovery"
Eran, This is a really solid doc. As you requested, here's my first-pass feedback, broadly divided into formatting/wording and structure/substance: FORMATTING/WORDING: All As a rule, a hyphenated name or phrase used as a heading or proper noun uses First-Letter-Caps, e.g. heading "7.3 Site-meta Document" should be "7.3 Site-Meta Document". In running text, it should either be "Site-Meta" (proper noun) or "site-meta" (generic noun) but not "Site-meta" (except, if it is generic noun, when capitalized at the start of a sentence). 3. (whole section) You hyphenate "resource-discovery" and "service-discovery" throughout, I think to emphasize them as separate terms, but they are not hyphenated in normal use or elsewhere in the document. I wouldn't hyphenate them in this section or elsewhere. To emphasize the terms the first time you use them in this section you could use quotes or italics. 5. third para: "In the case of multiple descriptors, selecting which descriptor to use is application-specific using factors such as the descriptor document format, accessibility, and other typed relationships, and is beyond the scope of this memo." Suggest breaking into: "In the case of multiple descriptors, selecting which descriptor to use is application-specific. It may involve factors such as the descriptor document format, accessibility, and other typed relationships, and as such is beyond the scope of this memo." paras 5-7 (the example). I found it confusing that the text says, "For example, the following HTTP response header returned with the HTTP representation of the resource http://example.com/resource/1" and then the example shows: Link: <http://example.com/resource/1;descriptor>; rel="describedby"; type="application/xrd+xml" You don't explain Link Templates until later in the doc, so it baffled me why "http://example.com/resource/1" and "<http://example.com/resource/1;descriptor>" didn't match. I'd either take out ";descriptor" in this example -- so the two URLs match as the reader expects -- or explain here why they are different. 6. first para: "A somewhat complete analysis of the potential methods..." Suggest, "A reasonably complete analysis of the potential methods..." 7.3 second para: "It can be considered a registry for "known-location" resource..." should be "resources" third para: "Site-meta offers a convenient location for storing information about how to map between resource URIs to their descriptor URIs" should be either "map resource URIs to their descriptor URIs" or "map between resource URIs and their descriptor URIs". third para: "...provide descriptor locations to URIs with schemes other..."/s/"...provide descriptor locations for URIs with schemes other..." STRUCTURE/SUBSTANCE 3. First Para: This seems to overlap quite a bit with the Intro section. The rest of the section draws a very useful distinction between resource discovery and service discovery. Suggest: a) renaming this section "Resource Discovery Vs. Service Discovery", b) flipping the order of first and second paras. 3. I think your definition of "service discovery" can be tightened and I have some other feedback about how this section can make its point (which I completely agree with), but that can wait until the next draft. 4.3 bullet #2: You say, "The resource descriptor document is retrieved and parsed based on the descriptor document format used." I think the point you made in section 1 is that retrieval is NOT based on the descriptor document format used but should be generic for all descriptor formats. That means only parsing would be format-specific, no? 4.3 last sentence: You say, "Capabilities usually carry a known identifier that can be matched to a database of known capabilities by the consuming application." I'd broaden that (thinking about RDF and XDI) to something like, "Capabilities are usually described with identifiers or description languages that the consuming application can match to a database of known capabilities or process via an interpreter." 5. Heading: Currently "Resource-Descriptor Link Relationship". This term really confused me standing alone as a heading. Were you talking about the Resource? The Descriptor? The Link Element? The Link Header? I had to read the section to figure out what it covered. Suggestion: use a longer but more self-descriptive heading such as, "Link Between Resource URI and Descriptor URI" 6. Second set of bullets. In my first reading, the text introducing this set of bullets says, "The methods are:" I continued reading, saw the references and technical meat, and thought, okay, these are the actual definitions of the methods. Then I kept reading and thought, hmmm, these are pretty short definitions for a spec like this. It wasn't until I read further that I realized that the full definitions were in the following section. So three suggestions: a) change the intro sentence to: "The three methods, described in detail in the next section, are:", b) number the bullets (1, 2, 3), c) keep these three paras to just plain English descriptions so as to quickly educate the reader without introducing any technical details or references here, and move all those down into sections 7.1, 7.2, and 7.3. 6. Second-to-last bullet. You say, "...all methods MUST produce the same resource descriptor (either by returning the same descriptor URI or a different descriptor URI that points to the same descriptor document content)." The latter part confuses me. Do we really want to promote the same descriptor document living at different URIs? Or did you mean different aliases that redirect to the same URI? 7.2 How much of this section repeats normative requirements of I-D.nottingham-http-link-header vs. how much are new requirements of this profile? It's good to repeat the most relevant requirements here, but it's important to distinguish which ones are from that spec versus which ones are unique to this "profile" of that spec. You might even want to break them into a 7.2.1 and 7.2.2 to do that. 7.3 Fourth/Fifth Paras: - I think I know what you are trying to say here but these paras are not enough to communicate a really hard concept -- which is actually quite a critical one for implementers. I personally think this point requires a longer explanation and at least one example and thus should get its own subsection called something like "7.3.1 Abstract Site Vs. Concrete Root Resource Description". 7.3 Sixth Para+: This section is so important that I would break it be broken into its own subsection called "7.3.2 Link Templates". ********** That's all I have tonight. Again, great job. I hope all our specs in this cycle end out this clean. =Drummond > -----Original Message----- > From: Eran Hammer-Lahav [mailto:eran@hueniverse.com] > Sent: Wednesday, January 07, 2009 11:41 PM > To: xri@lists.oasis-open.org > Cc: Mark Nottingham > Subject: [xri] Pre-draft of "HTTP-based Resource Descriptor Discovery" > > Please do not share this outside the TC until it is published officially. > > Attached is my working copy of the 'HTTP-based Resource Descriptor > Discovery' proposal. I still need to clean up the last third, but please > do provide feedback both editorial and content. Editorial changes at this > point should be sent directly to me. Content should be discussed on the > list. > > I plan to spend most of Thursday cleaning it up and pushing it out as an > IETF I-D. I will then move back to working on the XRD 1.0 schema document. > > There is nothing new in this document except for additional details about > HTTP response codes and such. Also, it uses the current published /site- > meta schema and not the new text-based format. This will be changed as > soon as there is something to reference. > > EHL
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]