Editorial comments on Dec 2003 WD of webarch

Here is a first set of comments, editorial; I plan on sending somewhat
more substantive comments in the upcoming days.

These comments were made on the document published at
http://www.w3.org/TR/2003/WD-webarch-20031209/

General comment on the doc:
Very pleasant to read, thanks to the numerous examples and the nice
formatting; I would have expected though that each section (<h4> level)
has a constraint, a principle or a good practice. Many don't, and they
often lack some clear message out of the section. Also, there are some
cases where distinguishing between what is wished/recommended and what
is currently true is made difficult by the formulation (I have
identified one below at least, wrt 4.1)

* 1.1.3. Principles, constraints and good practices
- The document defines design choices and properties but never uses
them. Are they needed at all, then?
- the document has 2 constraints, but it's not clear they fit in the
given definition
   - "The identification mechanism for the Web is the URI": is that
really a 'restriction in behavior or interaction within the system', or
rather a 'a fundamental rule that applies to a large number of
situations and variables' (ie a principle)
   - "Web architecture does not constrain a Web resource to be
identified by a single URI." -> a constraint which 'does not constrain'?
- I would find the distinction principle/good practice/constraint easier
to understand and more relevant if they were positioned with the answer
of 'what breaks if you break this rule' (the Web, the user experience,
the social expectations, ...?)
http://www.w3.org/TR/2003/WD-webarch-20031209/#app-principles

* "Silent recovery from error is harmful"
The formulation of the principle loses most of the context; what about
"User agents SHOULD NOT silently recover from errors" 
http://www.w3.org/TR/2003/WD-webarch-20031209/#no-silent-recovery

* "Language extension" definition
The language extension definition seems awkward in comparison with the
usual terminology; an extension to XSLT or SOAP or most languages I can
think of is used to designate the additional part of the language,
rather than the superset of the language including the basic language +
the additional part. That is, if A is the basic language, B, the
additional part, extensions usually refer to B rather than A+B
http://www.w3.org/TR/2003/WD-webarch-20031209/#def-lang-extension

* 1.2.4 Protocol based interoperability
The message of the section is not clear; "important interfaces are
defined in terms of protocols"... rather than?
http://www.w3.org/TR/2003/WD-webarch-20031209/#protocol-interop

* 2.4 "Each URI scheme has a normative specification "
-> each registered URI scheme...
http://www.w3.org/TR/2003/WD-webarch-20031209/#URI-scheme

* 2.5 MUST NOT attempt to infer 
-> MUST NOT infer
http://www.w3.org/TR/2003/WD-webarch-20031209/#pr-uri-opacity

* 3.3.2 "Suppose, for example, that the authority responsible..."
Why not reusing the example given in the story above?
http://www.w3.org/TR/2003/WD-webarch-20031209/#frag-multiple-reps

* 4.1 "In modern textual data formats, the characters are usually taken
from the Unicode repertoire"
Is that really the state of affair, or rather what modern textual
formats should do? It seems that the adjective "modern" is used to
suggest that it's what textual data formats should do to be modern,
rather than to describe the current reality.
http://www.w3.org/TR/2003/WD-webarch-20031209/#binary

* Term index
- what about calling it "glossary"?
- could you link it from the <head> of the document using <link
rel='glossary'>?
- also, for sake of making the document easier to scrape for the
Glossary project, could you add a class='glossary' to the <dl> enclosing
the definitions list?
http://www.w3.org/TR/2003/WD-webarch-20031209/#index

Hope this helps,

Dom
-- 
Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org

Received on Tuesday, 17 February 2004 10:03:06 UTC