Re: Comments on arch doc draft

Dan Connolly wrote:
> I presume these comments regard
>   http://www.w3.org/2001/tag/2002/0607-intro
>   Mon, 17 Jun 2002 20:32:20 GMT

Yep.  Nice to get some forward motion on this debate.

> > TB2. Document's intended usage
> >
> > I suggest that the primary usage of this document will be in reference 
> > mode, so that arguments can take the form of "As it says in section 
> > 2.3.1 of the Web Arch, you have to use GET".
>
> Wow... that seems like a 180-turnaround from when you chided
> me about quoting from http://www.w3.org/DesignIssues/ as
> if it were scripture.

I didn't dispute the need for scripture, I just didn't think that 
document worked very well as such, thus the need for this one.

> I'd much prefer folks to quote at least one-liners from
> this document, rather than section numbers.

Really?  The section will probably include a couple of supporting 
examples and supporting prose.  However I agree that the one-liners 
should be addressable.

> >  I think the document 
> > should be designed to support this usage even if it is thereby made less 
> > useful as a tutorial or rhetorical resource.
>
> There's a risk that we'll whittle down the text to the point
> where folks stop complaining but we don't really agree on
> very much. It's important to me that the substance
> of Web Architecture is captured to the point where
> folks understand and agree.

Fair enough, if we cut away what feels like fat and there's not much 
left then we'll know we've gone too far.  I'm actually impressed at the 
number of areas where we seem to have working consensus.

> > TB4. Prune Abstract
> >
> > Remove all but the first sentence of the abstract, and reword it 
> > slightly to read "This document is designed to serve as a reference to 
> > the architectural principles which underly the World Wide Web."
>
> "designed to serve" doesn't work for me. I prefer to
> actually abstract the document, i.e. say the
> same thing in much fewer words:
>
>         The World Wide Web is a networked information system.
>         Web Architecture is the set of rules that all agents in
>         the system follow that result in the large-scale effect
>         of a shared information space. Identification,
>         data formats, and protocols are the main technical
>         components of Web Architecture, but the large-scale
>         effect depends on social behaviours as well.

Let's do both.  "This document is designed to serve as a reference to 
the architectural principles which underly the World Wide Web.  The 
World Wide Web is a networked..."

> > TB6. Define terms
> >
> > I think there is scope for defining terms for use in this document and 
> > for external reference.  Obvious examples are "agent", "client", and 
> > "server".
>
> Hmm... those seem like terms from the reader's vocabulary,
> not terms introduced by or defined by this document.
>
> The terms that deserve definitions are things like resource,
> dereference (uhg!), maybe link... the ones I'd expect
> are pretty much already treated (resource is in bold.
> deference has its own section heading; we haven't gotten
> to 'link' yet, somehow.)

It's good they're in bold, each should be linked to its formal definition.

> > TB7. Clients/Servers/Agents

> > So 
> > I recommend "agent" as a defined term.
>
> OK, I can go with that, as long as "clients and servers" is
> in/near the definition. (I note that "client" occurs only
> once in the document, so aside from <dfn> or some such
> around the 1st occurence of "agent", I don't see
> what change you're asking for).

I think that once we get into the undeveloped sections, there are going 
to be a few principles saying "Agents MUST blah blah blah...", it would 
be nice if Agent were a linked defined term.

> > TB8. Results of having an architecture
> >
> > Current doc says "that result in the large-scale effect of a shared 
> > information space."  I recommend "that result in the system working 
> > correctly and exhibiting good performance characteristics."
>
> I strongly disagree.
>
> The essential characteristic of Web Archiecture is the
> emergent property of a shared information space.

But there have been other shared information spaces: OCLC's union 
cataloguue, the archie/usenet/ftp pre-Web internet, Xanadu.  The 
distinguishing factor of the Web is that it works unsurprisingly and 
scales nicely.  The reason for that is the architecture.  I think it's 
important to say that if you break these architectural principles you 
can expect nasty surprises and performance problems.

> > TB11. Lose last paragraph of introduction
> >
> > The one beginning "The rules are kept to a minimum..."
>
> Strongly disagree; maybe we should beef it up to its own section:
> the principle of minimal constraint.

As it stands, it's a conversational observation that adds little.  If 
you'd like to draft something with normative force, why don't you do that?

> > TB13. Introduce "resource" where?
> >
> > I think "resource" should be a defined term in this document, where is 
> > it introduced?  Start of chapter 1 is as good a place as any.
>
> Yes, it is introduced/defined right at the start of chapter 1.
> I don't see what you're asking for.

A place to point at where the term Resource is formally defined.  Trust 
me, such a pointer would be very widely used.

> > TB15. Principle #1
> >
> > Could this be stronger?
>
> I'd like to think so, but choosing the words is tricky...
>
> > Along the lines of "Anything which has a URI is 
> > by definition a Resource and thus part of the Web.  Anything which 
> > doesn't is not.
>
> It's kinda hard to say what "X doesn't have a URI" means.

Well, the XMLP guys were building a world in which many things that 
could have been resources would never be because they couldn't have a 
URI.  We're trying to say "don't do that".

> It's clear(er) what it means to say "X doesn't have
> a well-known URI" or some such, but it's tricky...
>
> > Everything important, including units of information 
> > and service as well as widely-shared abstract notions, SHOULD be a 
> > resource."  I'd love to find a way to use MUST in here.
>
> I tried to think of one, but I'm back to thinking this is
> a general principle, not an absolute rule.

Yeah, but it's arguably the most important of all the rules we're going 
to write down, so stronger is better.  I agree it's hard but probably 
worth the work.

> > TB16. URI & reference

> > 1. URI - not relative, no fragment.  This is what is sent from an agent 
> > to another in the dereferencing process.
>
> sorta; the URI doesn't really go over the wire intact;
> not in most HTTP requests, at least.

er right, I meant "input to the dereference operation"  or some such

> > 2. Fragment-free URI Reference - relative allowed, no fragment.  As an 
> > example, XML 1.0 requires SYSTEM identifiers to be of this class.
>
> > 3. Absolute URI Reference - relative disallowed, fragment allowed.  In 
> > practice, almost all XML namespace names are of this class.
>
> I agree we should single this class out; this is the class
> of identifiers that forms the abstract information space.

I think I'ved an existence proof that these all need to be singled out. 
 If people are gonna be subsetting 2369, it would be good if there were 
a few standardized named ways to do it.

> > 4. Unrestricted URI Reference
> >
> > W3C Recommendations MUST be clear as to which class of identifiers they 
> > support."
>
> W3C recs must be clear, period. I don't see the point of this
> last sentence. It might be worth giving an example of
> what *not* to do; or we could say "don't sling the term 'URI' around
> casually; cite RFC2396 by section number [or this arch doc?]
> when you import these terms into specs."

I think your last point could be reworded as "W3C Recommendations MUST 
be clear... " etc :) - if you're not going with an unrestricted URI ref 
you should probably go through the arch doc.

 -Tim