commentary on webarch 07/16

A large, number of points, mostly editorial.

General comment: the content of this draft is very good; I have few 
technical quibbles.
General comment: the language is insufficiently paranoid; this document 
will be beaten to death word-by-word by fanatics and lawyers; one 
consequence of this is that the fewer words, the better.  Quite a few of 
my comments are along the lines of "take X out".  In general, unless it 
is 100% clear that for any X, unless X is essential to the correctness 
or comprehensibility of the document, X should go.

I've marked some comments with **, they are the ones which might need 
TAG discussion as being not entirely editorial.

1. <ol> 1. , called resources,

** 2. 1. Editor's note.  This goes in the protocols section, right?

3. 1.1.1 "writing down" hmm, "documenting"

4. 2. I think "defined *in*" is better than defined by

5. 2, 1st para; lose 2nd sentence, it's fluff.

** 6. 2, 2nd para; we don't really mean exponentially, we mean "as a 
function of".

7. 2. sentence beginning "Although there's no precise definition...", 
just say "Examples of important resource include those that a third 
party might reasonably want to....

8. 2.1 Awkward start.  Communication between parties is facilitated by 
the ability to establish when they are talking about the same thing. 
Then lose the second sentence.

9. 2.1 "Agents that reach conclusions about identify by means other than 
those publicly documented in relevant specifications take responsibility..

10. 2.1 Lose sentence beginning "Web servers may vary..."

11. 2.1 Lose word "mere" in "mere inspection"

12. 2.1 Lose sentence "In this case, the URI should...."

** 13. 2.1 Section beginning "URI consumers cannot, in general, ..." may 
deserve its own numbered section "URI Opacity".  It's really not about 
comparison any more.

** 14. 2.2 Why say "scheme names" if "scheme" will suffice.

15. 2.2, 2nd para, do you mean the HTTP scheme specification?  Incorrect 
as stated.

** 16. 2.2 "We note in passing..."  Don't.  Either promote this up with 
the URI generalities or lose it.

** 17. 2.3 3rd para is subtly wrong.  They have the confidence they're 
talking about the same thing because they're using the same URI; we've 
established that above.  They can have confidence that their 
understanding of the meaning is shared if they defer to the authoriy of 
example.com in establishing that meaning.

** 18 2.4 "additional identifying information that is selective with 
respect to that resource."  No, this statement is incorrect.  You mean 
"additional information information that is interpreted in the context 
of that resource representation"

19. Good practice at and of 2.4; subtle change ".. SHOULD NOT use HTTP 
content negotiation for resources that have multiple representations of 
different media types...."

20. 2.5 First sentence is weak ".. as might be characterized".  How 
about simply chopping it off after "resource".

** 21. 2.5.1 "The representations communicate *information about* the 
state of a resource".  Please; some literalist is going to read this and 
assert that, per webarch, a representation must communicate the complete 
state of a resource.

22. 2.5.2 "Subscription services" isn't specific enough; how about 
"subscribing to a publication"

23. 2.5.2 I think the example could be a little simpler; why not just 
say that it is incorrect to have a link which, when followed, subscribes 
you to the list.

24. 3. intro sentence.  Same comment as #21 above; let's be 
super-careful to say that the representation communicates information 
about the state of a resource, and stop there.

25. 3. typo: "consists those bits"

26. 3.1 typo: "owner of a resource assign URIs for that resource" - 
sanity-check whole sentence.

27. 3.1 inconsistency between the metadata and the "content"; "what is 
specified in a format" is kind of confusing.

** 28. 3.2.1. The "Author needs" and "User needs" bullet points are 
essentially content-free; motherhood is good too.  Please lose them.

** 29. 3.2.1 Consider adding attention to internationalization as a 
top-level bullet.

** 30. 3.2.2.4 First sentence is wrong; extensibility covers way more 
than other vocabularies, it also covers adding markup to this one, and 
modifying existing syntax and semantics.

31. 3.2.4. Can we distinguish the HTML markup with <code> or whatever?

32. 3.2.4, 2nd para, sentence beginning "And" is a bit awkward; combine 
the two of them?

33. 3.3, 2nd para, the trailing half of the sentence about IETFXML is 
superfluous.

34. 3.3.2 4th para, incorrect plural, "relative URI".

35. 3.3.2, 4th para, Shouldn't "Namespaces in XML" be distinguished or a 
bibref or some such?

36. 3.3.3 first <ul>; add "learn how to use the markup vocabulary in the 
namespace"

Received on Thursday, 17 July 2003 20:39:55 UTC