Review of Oct. 27 webarch

I just finished reading the Oct. 27th webarch.  Before I get into 
details, I want to emphasize that starting now, we *must* have 
stability in this document if we are to get to last call by year-end.  
The organization may not be perfect but it's plenty good enough, modulo 
one section which I argue for removing.  Please, from here on in, can 
we agree on no more moving things around from section to section and no 
substantial introduction of new material?  Among other things, I don't 
think I have the strength for too many end-2-end walkthroughs, but if I 
have some confidence in the overall stability I'm happy to pitch in 
with point reviews on this section or that.

Overall impression: it's getting there.  The vast majority of edits 
here are along the lines of lose this, cut that, general tightening up.

=== Abstract 
=============================================================

Slight rev for style on abstract opening:

The World Wide Web is a network-spanning information space consisting 
of resources which are interconnected by links.

revise list of actions to: "and proxies) retrieve, create, display, 
analyze, and reason about resources."

2nd para: s/both// in 1st sentence

s/and the protocols/and of the protocols/

s/define the interaction/support the interaction/

===== Status of ===========================================

The sentence beginning "Where current practice conflicts..." is foggy 
and won't wear well with time, do we really need it?

Same question for the next sentence beginning "Some published 
specifications..."

=== 1. Introduction ====================

<ol> 2. s/complete or partial//

======= 1.1 About this Document =========

s/is an an ongoing attempt to/attempts to/

==== 1.1.2 Scope of this document ========

The sentence about REST is correct but "theoretical and modeling work" 
read awkwardly to me.  I tried a redraft:  "Researchers in this area 
have proposed a theoretical basis and formal model for Web 
architecture, notably including Roy Fielding's..."

=== 1.2.1 Orthogonal ====

Lose the sentence "Specifications should identify orthogonal 
abstractions" it's pretty well content-free.  In fact, I think that 
whole paragraph could get lost and we come out ahead.

== 1.2.2 Error Handling =======================

Rephrase 1st sentence: "Errors occur in networked information systems.  
The manner in which they are dealt with varies..."

<ul> first

s/"halt and catch fire"/fail deterministically/
s/agents that halt-and-catch-fire/such failures/

<ul> 3rd

s/sufficient/appropriate/twice, or even better just lose that third 
bullet point with the language about people and processors, I don't 
think it adds much

===1.2.3 Distributed System ====================================

s/Web as/The Web as/

But I have concerns with this whole section, maybe I wasn't there but I 
don't recall any TAG discussion or consensus behind it, a couple of the 
bullet points e.g. about robots.txt

=== 1.2.4 Syntax ==========

Do we have consensus to use the DanC text with some work on last 
sentence?

====== 2. Identification ==================

last sentence 1st para: "Uniform Resource Identifiers, which are global 
identifiers in the context of the web, are central..."

2nd para: s/linked/accessed/ or maybe s/linked/linked-to or accessed/

=========== 2.1 URI comparisons ===============

2nd sentence "This freedom ... resources" the more I read it the less I 
get it.
s/This freedom does not imply that/Thus,/

====== 2.3 URI Schemes ==============

1st para last sentence s/specifies/may specify/ (some are deliberately 
silent)

"Deployed software is more likely to handle the introduction of a new 
media type than the introduction of a new URI scheme"  I used to think 
so, but this is actually true?

======== 2.4 URI Opacity =====================

1st para, sequence beginning "For example" rework a bit:

In general, one cannot determine the Internet Media Type of 
representations of a resource by inspecting a URI for that resource.  
For example, the ".html"...

======= 2.5 Fragment Identifiers ===============

Sentence "Note that the presence of a fragment identifier in a URi does 
not imply that the URI will be dereferenced."  Why would anyone suspect 
such an implication?  Why are we saying this?  Suggest losing it.

======  3. Interaction ================

Totally disagree with definition of "information resource" in the 
Editor's note, but we're going to lose that note anyhow right?

======= 3.1 Using a URI ======================

s/expectations themselves/expectations/

para beginning "Dereferencing..." suggest "Dereferencing a URI 
generally involves a succession of steps as defined in multiple 
independent specifications and implemented by the agent."

<ol> let's keep the style of all the <li>'s consistent, have each one 
start with "specification XXX states that", this is mostly pretty good 
except for it breaks down in item 4, which should say "[IANASchemes] 
specifies that the "http"....

and in item 5, it's a bit misleading since most agents don't themselves 
implement TCP/IP.

======== 3.2 Messages... ==================

"A message is an event..." is a bit opaque at first, how about: 
"Message syntax and semantics are specified in a non-exclusive set of 
protocols (e.g...."

2nd para "but not an HTTP POST" huh? wrong I think, the result of a 
POST can contain all that stuff.

======== 3.3 Internet Media Type =================

1st para, the agent doesn't accomplish its work by looking things up in 
the IANA registry, rather it dispatches as specified in there, much the 
same as the previous discussion about implementing semantics specified 
elsewhere.

======= 3.3.1 Media Types... ==============

s/no effect on/no interaction with/

====== 3.3.2 Fragment Identifiers.. ==========

s/At a given moment, for/For/

s/the following/that by design the secondary resource identified by the 
URI and fragment identifier using the U#F syntax is expected to be the 
same independent of representations/  tehn lose the <ol>

In the example beginning "Suppose, for example, "

s/identified resource/ the resource identified by "oaxaca/map"

===== 3.4 Authoritative .. ===========

s/Large numbers/Arbitrary numbers/

============= 3.4.1 Inconsistencies =======

the "(for example, due to security issues)" is weak, feels like a 
throwaway, either drop it or make it specific.

===========3.5 Safe Interactions =========

s/She completes/She enters data into/

===== 3.6 Representation Management ==========

update 1st sent to remove care & feeding: "The usefulness of a resource 
depends on good management by its owner"

======= 3.6.2 =========

s/(via some of the 3xx/using the 3xx/

===== 3.6.3 Access Control ==========

s/relies/rely/ (hmm, maybe)

==== 3.7 =========

s/for Interactions/for Interaction/

======== 4. Formats ==========

1st para s/formats for the Web/formats/

s/applications.  This evolution results/applications, resulting/

s/significant way/formal way/

"knowledge of its designers' intentions" Hmm, you're talking about the 
data-format designer here, not the actual message designer, needs to be 
clearer.

========== 4.2 Binary ================

s/media type of "text/"/media type beginning "text/"/

lose the entire sentence beginning "When data include sentences in 
natural language..."

======= 4.4 Separation ==============

s/Generally authors need to/It is good practice for authors to/

Should we touch on accessibility issues in this 1st para of 4.4?

======== 4.5 Web-Enabled Linking ==============

s/One of the interesting characteristics/A defining characteristic/

in discussion of active/passive links, need to go directly to example, 
pointing out that browser follows <img immediately, but waits for a 
click to follow <a

======== 4.6.2 XML Namespaces ====================

s/the "p" element/the <p> element/

in the stuff on global attributes: lose sentence "In that respect they 
are a somewhat special case", there are only elements and attributes so 
it's hardly a special case.

s/a great many elements/different elements/

Lose the last sentence about "As other schema technologies become..." 
why bother

===== 4.6.3 Links in XML ================

Para beginning "If a future revision" has a serious error, I can still 
define an XML-based language that has wildly different #fragid 
semantics from XPointer, so the notion that authors will be able to 
rely on whatever pops up in XML is at best misleading, this is only 
true if served as */xml not as */*+xml and is speculative anyhow.

======== 4.6.4 Namespace Documents ========

I do not think we have the requred level of consensus to support the 
list "OWL, RDDL, XMLSCHEMA, XHTML"  Unless pretty well everyone but me 
is prepared to sign up for this list, lose it.  I do not agree on 
XMLSCHEMA and I don't know enough about OWL to have an intelligent 
opinion.

====== 4.6.5 Fragids/IDs ======================

I don't think we need all this stuff about the details, can we please 
just chop this off after "...problematic in practice."?

====== 4.6.6 Media Types ==================

We lost one of our good practices, along with not using text/xml we 
need the language about not providing charset= for */*+xml unless you 
really know, because the downside is big and the upside hard to see.

====== 5. Conformance =========

Has there been TAG discussion on this?  I don't recall coming to any 
useful consensus on whether we should have conformance and if so how it 
should work.

Received on Wednesday, 5 November 2003 01:07:57 UTC