[Tim Bray] Review of webarch-20040816 (editorial issues)

I'm forwarding this to the comments list so that it gets integrated
into our tracking system. I'm breaking Tim's message into two parts,
one for substantive issues one for editorial issues.

attached mail follows:

*****************************************************************
*****Issues from here down are editorial.

**Abstract.

s/Within each of these/In each of these/

2nd para, make sentence smoother:

These lead to design choices for and constraints on the behavior of 
systems that use the Web, aimed at achieving the desired properties of 
the shared information space:

**1. Introduction

2nd para.  Suggest losing "(on behalf of a person, entity, or 
process)"... terms are fuzzy (entity?), and it doesn't really add 
anything.

1st story.  lose ", as advertised", redundant & awkward

list of "three architectural bases"... #2.
Suggest swapping 1st & 2nd sentences.

"By clicking on a hypertext link..." well, Nadia didn't, except 
implicitly in step #3 of the story.  In fact, she typed in the URI.  
Which doesn't weaken the point.

**1.1.2

2nd para.  s/This document strikes/This document strives for/... avoid 
being self-complimentary

**1.1.3 <dt>Constraint</dt>

s/certain properties/desired properties/
What are "non-functional properties"?  I don't think the division of 
desired properties into two baskets really helps.  Also, the list is 
too long and klunky, lose a couple.

**2.1

1st para.  s/sharing a URI/sharing URIs/

last paragraph feels orphaned and a little lame.  Last sentence is 
worth saving.

**2.2

3rd para.  The term "scheme" is used before being defined, and kind of 
abruptly too.  At least a hyperlink to its definition?

s/scheme specific URI/scheme-specific URIs/

**2.2.1.1

2nd para.  Does the "urn" scheme actually establish a unique 
relationship between a social entity and a URI?  Let's assume urn:uuid: 
gets registered some day

awkward phrase: "... based on Internet media type, validity 
constraints, or other constraints."  Also, is the phrase "validity 
constraints" well-understood?  I might assume that it's referring 
specifically to the result of XML DTD processing?  Maybe just "... 
based on Internet media type, user authorization, or other 
constraints."

**2.2.2

Wouldn't <cite>The Sting</cite> be better than "The Sting"?

/me weeps for the lost white whale... dammit, I'll charter a ship out 
of Nantucket and hunt that sucker down in the graveyard of lost 
specifications, I just need a Tahitian harpooner.

**2.3

This section suffers from severe internal confusion as to how the word 
URI is pluralized.... someone needs to take an end-to-end walk through 
the doc looking at each occurrence of "URI" to see whether it should be 
"URIs".

**2.3.2

The story makes Dirk look like a doofus.  How about an innocent mistake 
instead of a dumb question: "Dirk is editing a Web page, and Nadia 
notices that he has inserted a link to ...08/03/Oaxaca labeled 'Current 
Oaxaca weather forecast'.  Nadia spots a cut-and-paste error and 
explains that the resource Dirk has identified is the weather forecast 
for 'Weather on August 3, 2004', and that he should either change the 
label or change the URI to '.../oaxaca'"

**2.4

Para beginning "While Web architecture..." s/significant amount/large 
amount/

**3.1

In the discussion of URI stability, it should be noted that if a 
resource is an information resource, it should stay an information 
resource.

**3.2.1

<ol> after "Precisely which representations...", #4: suggest rewording 
to say "The world changes over time, and so representations of 
resources are like to change."

**3.3.1

Para beginning "As with any URI", s/licensed by specification/licensed 
by any specification/.

**3.3.2

s/restrictions on, or structure within,/rules for use of/

**3.4

para beginning "In all cases the accuracy"

s/In all cases the accuracy/The accuracy/

**3.6

1st story s/(and he trusts them more than he trusts the Web site in 
question//, hardly necessary.

1st Good practice s/the identified resource/the resource it identifies/

**3.6.1

1st para, 2nd sentence, suggest rewrite: "For an Information Resource, 
persistence depends on the consistency of representations."

**3.7

1st para: instead "exchanging" how about "passing on" or "republishing"

para beginning "For resources that are..." s/applicability/reusability/

**3.8

Bah.  Content-free.  Unhelpful.

**4.

Suggest rewrite 1st sentence: Data formats (examples include XHTML, 
RDF/XML, SMIL, XLink, CSS, and PNG) [er is XLink a "data format"?] are 
agreements on the correct interpretation of representation data.

2nd para s/data sender/sender of data/
s/data receiver/the party that receives it/.

**4.1

3rd para. suggest rewrite 1st sentence: If a data format is textual, as 
defined in this section, this does not imply that it should be served 
with a media type beginning with "text/".

**4.2.2

2nd para after story s/For almost all applications/In general/

**4.2.4

1st <li> in <ul>
s/they have little or no effect/they are not intended to affect/
... hmm, is this really true?  Ask Norm, he understands JFIF

2nd <li> s/to be composed/content/

3rd <li> s/vocabularies is/vocabularies are/

**4.4

1st para s/birth/success/

**4.5.6

2nd <li> in <ol> s/ID assignment/ID recognition/.  "Assignment" really 
feels like the wrong word.

**5.1

last sentence.  The "advances into territory" metaphor is perhaps a 
little martial... does it leave the tents of the other specification 
burning and its women weeping?  Perhaps "overlaps" would do?

**5.3

1st sentence: s/can be well-specified/can be well-characterized/