Re: [Generic Resources 53] Updated Finding On Linking Alternatives And Discovery

Raman,

Mostly this looks fine and ready to go.  I did notice a few more purely 
editorial issues, though the first two are significant and need to be 
fixed.  That one is that the status section has a statement "An informal 
guide to previous discussion of this topic is available and may be useful 
to reviewers of this draft."  The link is in fact to the draft itself.  I 
strongly suspect that this entire sentence traces to your perhaps having 
adopted the metadataInUri draft finding as a starting point.  It had such 
a link to informal discussion, so my guess is that this entire sentence is 
to be deleted.  Anyway, the link is bogus. 

The other significant comment is that you also have carried over the usual 
reference to RFC 2119, but in fact the formal uppercase SHOULD, MUST, MUST 
NOT, etc. are not used in the finding.  I suggest that the sentence in the 
status, and the corresponding bibliography entry be dropped.  (Warning: I 
do comment later on one place in which the finding uses the odd 
capitalization Should Not;  my recommendation is to lowercase that one, 
but if you uppercase it, then obviously you should keep the RFC 2119 
reference after all.)

Other less significant comments follow.  I think most of these are worth 
fixing, but I leave that entirely to you.  There are a fair number of 
them.  If you want to fix only the two above and ship, I'm fine with that. 
 I don't think the suggestions below are the sort of thing that would 
trigger another round of formal reviews.  Most are typos or barely above 
that in significance.  I'm afraid these are in the order I discovered 
them, which is not necessarily document order.

If you find that you do want to fix these but that the editing is 
burdensome, I'll be glad to share the load.  We can pick a time when the 
CVS copy is clean and I'll be glad to help patch up some of these, 
particularly where the issues are just punctuation and spacing.

---
From 2.1.1 list item 5:

"In contrast, links meant for machine consumption, e.g., Atom/RSS feeds 
might use the HTML link element."

I think that this is hard to parse, partly due to the position of the 
commas and partly due to the wording.  I think what you meant was that 
Atom/RSS feeds are examples of resources to which an HTML document might 
link for purposes of machine consumption.  My eye tends to hang up on the 
comma after the e.g., and tries to parse as "Atom/RSS feeds might use the 
HTML link element", before backtracking and realizing that's not intended. 
 Proposed rewording:

"In contrast, links meant for machine consumption, e.g. links to Atom/RSS 
feeds, might use the HTML link element."

---
From 2.1.1:


"If no content negotiation is in place, Serve a canonical representation 
of the content at http://example.com/ubiquity/resource"

The word "Serve" should be lowercase.

---
The punctuation that terminates list items is inconsistent throughout the 
finding.

For example in the abstract, there's a list of:

        Representations appropriate for different delivery contexts,
        Representations in different languages,

I'm not sure why these end with commas.  The style guides I've seen mainly 
say to use periods for list items if and only if they are each complete 
sentences, and otherwise to use no punctuation at all.  In any case, the 
commas look suspect. 
---
In chapter 3:

"As can be seen from the use-cases and suggested solutions enumerated in 
the previous section, pointers to Web Resources (URIs) can either:

    * Be canonical URIs, i.e., have no context hard-wired.
    * Can encapsulate partial context, e.g., encapsulate language,
    * Encapsulate multiple context bits, e.g., language and device 
profile,
    * Capture all context, i.e., the creator of the URI guarantees that 
all state is completely captured by the URI."

I think the word "Can" should be deleted from the second item in the list.
---

In the abstract:

"This document explores the issues that arise in this context, and 
attempts to define best practices that help toward:

    *  Preserve the One Web while enabling content publishing to a 
multiplicity of delivery contexts.
    *  Enable automatic discovery of the available representations.
    *  Enable the creation of RESTful URIs that remain representation 
agnostic while delivering the correct end-user experience."

I think it would be better grammar to delete the word "toward", so the 
list can be interpreted as "practices that help Preserve the One Web", 
"practices that Enable automatic discovery", etc.

---

In the very first sentence of the introduction:

"There has always been a need to serve user-agent specific contents for a 
given URI --- thus highlighting the distinction..."

you have approximated an emdash with three hyphens, which looks sort of 
bad.  For your convenience, this is a real emdash — you can copy it if you 
like, or else use the entity —.  A useful guide to dashes and their 
use in HTML is at [1].

--

I hesitate to raise this, because it's more a question of patching around 
bugs than doing things right, but both Firefox and IE tend to render the 
text in <code> elements too small relative to the text around them.  I've 
seen this discussed on the Web, but I'm not sure why the problem occurs. 
Anyway, to get around this, I reluctantly made the drafts of metadata in 
URI point to a stylesheet (which happens to be metadataInURI.xsl in the 
same doc directory as your finding) which has in it:

        code        {font-family: monospace;
                     font-size: 130%;}
        pre         {font-family: monospace;
                     font-size: 120%;}

in the generated HTML <style>.  I find this makes the text sizes line up 
better.  Others may disagree.

---

Chapter 3:

"URIs are cheap, we suggest creating as many distinctive URIs as is 
meaningful."

I believe that the correct punctuation to join the independent clauses is 
a semicolon:

"URIs are cheap; we suggest creating as many distinctive URIs as is 
meaningful."

---

Similar issue also in chapter 3:

"The hyperlink structure of the Web is crucial for content discovery; When 
creating..."

One option is to leave the semicolon, I think, but then the word "When" 
following the semicolon should be lowercase.  Otherwise, I think you could 
make the semicolon a period, and leave the "When" in caps.

---

Also in that same list, the 3rd item has:

"in the absence of user context; Or equivalently"

There too, I think the "Or" should be lowercase.

---
Chapter 3, same list:

"Contrast these findings with the metadata in URIs and state finding which 
each enumerate use cases where user context Should Not be encapsulated by 
URIs"

That "Should Not" has only initial caps.  I think it should either be all 
caps or no caps.  My vote, as signaled above, would be to make them 
lowercase, as nowhere else in the finding do we use RFC 2119 directives. 
If you want to make them uppercase, then obviously you should not follow 
my advice above on getting rid of the RFC 2119 reference in the status and 
biblio.

---
Chapter 4:

"URIs are cheap, create them as needed, publish them to the Web, and 
ensure that they are appropriately linked in to the rest of the Web. Thus, 
each representation of interest should get it's own URI and there should 
be one additional URI representing the generic resource."

More independent clause punctuation.  I think that should either be "URIs 
are cheap. Create..." with a period, or else "URIs are cheap; create..." 
with a semicolon.  The comma seems incorrect to me.
---
Chapter 4:

"Thus, given one of the alternatives for a resource,ensure "

Missing space before the word ensure.
---

That's it.  Sorry I didn't catch more of these before.  Again, I'm very 
happy with the substance of the finding.  Thanks for the hard work on 
this.

Noah

[1] http://alistapart.com/stories/emen/


--------------------------------------
Noah Mendelsohn 
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------

Received on Wednesday, 13 September 2006 23:13:35 UTC