editorial comments on Web Architecture document

Thank you for the opportunity to review this document.  It seems worth
a thorough review; in this and following notes I include various
comments.  In this mail I have grouped various comments which seem to
me mostly or basically editorial.

................................................................

(a) Illustration

The shadows in this graphic convey no information; they are (in the
sense defined by Edward Tufte) chartjunk.  Please remove them!

................................................................

(b) 1.1 About this document

Bulleted list, third item.  For "the addition a conformance section"
read "the addition of a conformance section".

................................................................

(c) 1.2.1 para 2.  What is the subject of the verb "needing" in this
paragraph?

................................................................

(d) 1.2.1 para 3.  The verb "deserve" in this paragraph seems to
introduce notions of merit, virtue, and vice which seem unusual in a
technical context; it seems almost like a category error. Are you sure
there is no other word which would be better here (e.g. because it
avoids inviting the reader to consider the possibility that the
document is committing category errors)?

................................................................

(e) 1.2.2 para 4.  Are the "language extension" and the "extension
language" mentioned in this paragraph the same or different?

................................................................

(f) 1.2.3 Error handling, list item 2 uses the phrase 'fail
deterministically'; I'm not sure this is a meaningful phrase. To the
extent that I can assign a meaning to it, it seems inaccurate as a
description of XML's draconian error handling.  Specifically, what's
deterministic about it?  The XML specification does not define a
particular error code, error mode, or error behavior.  I think you
just mean that processors will definitely fail, and are required to do
so.

................................................................

(g) 1.2.4 para 2.  'This leads to the well-known "view source" effect'
--
'This' has no identifiable antecedent (direct exposure to the
messages?  the fact that users don't commonly have direct exposure?
the fact that although 'less commmon' it is not 'unusual'?).  You need
to work a little harder to discover what it is you would like to try
to say here, and then work a lot harder at saying it.

................................................................

(h) Section 2.3, para 1.  I encourage you to cite the copies of Moby
Dick in the Oxford Text Archive in addition to (or instead of) the
version produced by Project Gutenberg, which lacks any metadata about
the print edition from which it was transcribed and is unfortunately
not a good example of transcription practice.  The OTA catalog shows
versions of Moby Dick at

  http://ota.ox.ac.uk/search/info.perl?show=ID0628
  http://ota.ox.ac.uk/search/info.perl?show=ID1629
  http://ota.ox.ac.uk/search/info.perl?show=ID1828

................................................................

(i) Section 3.3.1, para 1 ("Per [URI], in order ...") says in part
"The Internet Media Type of the retrieved representation specifies the
authoritative interpretation of the fragment identifier."  Is
"specifies" really the right word here?  I would have thought it was
the definition or description of the Internet Media Type which
specified the interpretation; the media type itself is associated with
such an authoritative interpretation, but whether I take the term
"Internet Media Type" to denote strings like "text/xml" or "text/html"
or to denote some abstract object for which "text/xml" and "text/html"
are names, either way the media type itself is not the kind of thing
that seems to make sense as the subject of the verb "specify".

................................................................

(j) Section 4, para 2, says "making good use of a data format requires
knowledge of its designers' intentions."  This is an instance of the
intentional fallacy which undergraduate students of literature are
(rightly) taught to avoid.  The designers' intentions are certainly an
interesting object of contemplation, but not nearly as relevant to
making use of a data format as the close study of what they actually
specified.  What we accomplish in reality is not always identical to
our intentions, and intentions are at best an unreliable guide to what
a specification actually does.  To take a concrete example: judging by
the text of the introduction to the first edition of the XML
Namespaces Recommendation, one would have to conclude that the
designers intended to provide universally unique names for XML element
types and attribute types.  In reality they achieved a somewhat
different goal, namely that of allowing the definers of XML element
and attribute types to distinguish their own creations from those of
other creators -- this in itself would provide unique identifiers only
if namespaces were constrained not to use local names with more than
one denotation, but the Namespaces Rec avoids making any such
restriction on the internal structure of namespaces.  Any
interpretation of XML namespaces which allowed itself to be guided by
the designers' apparent intentions would be led into a cul de sac.

Recast the sentence.

................................................................

(k) Section 4.1, Note.  Please revise this sentence to avoid using the
verb "comprise", which is frequently misused (as I believe it is here)
in place of "composed", is easily misunderstood whether used correctly
or incorrectly, and regularly distracts careful readers into a brief
consideration of whether or not the reader can safely trust the text
to mean what it is saying.


-C. M. Sperberg-McQueen

Received on Thursday, 4 March 2004 18:06:41 UTC