Re: Comments on arch doc draft

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

On Thu, 2002-06-27 at 16:36, Tim Bray wrote:
> 
> Numbered to see if this helps improve productivity of debate.
> 
> TB1. Document title
> 
> I Suggest "Architectural Principles for the World Wide Web"

That's better than "Intro..." but I think I want more
than principles. Hmm...

> 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'd much prefer folks to quote at least one-liners from
this document, rather than section numbers.

>   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.


> TB3. Minimalism
> 
> I think this document should contain *nothing* but succinct statements 
> of architectural principles supported wherever possible by examples, and 
> the minimum necessary text to make sure each principle is correctly 
> understood.  I think that the bulk of text to motivate, evangelize, and 
> provide context for the principles should go elsewhere (for example, 
> maybe our findings, see below).

Hmm... I was going to flatly disagree, but maybe not...
do you have any specific text that should go?


> 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.


> TB5. Lose '@@' section in 2nd para of Status of this Document
> 
> 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.)

>  The xmlspec vocabulary provides all the machinery necessary 
> to do this.
> 
> TB7. Clients/Servers/Agents
> 
> The introduction talks about clients, servers, and agents.  It would be 
> simpler if we could write all our architectural principles purely in 
> terms of "agents" and have them apply to any software using the Web.

Yeah, but I think the loss of "tutorial value" wouldn't be worth it.

For just the cost of two words, client and server, we distinguish
the sort of agents we mean from many other uses of the term 'agent'
in computing.

>  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).

>  It may be the case that there 
> are architectural principles that apply only to "servers" or "clients" 
> in which case we'll need to define those terms.  Right here in the 
> introuction seems like a good place to do it.  If we do manage to get 
> away with just using "agent" then a sentence here explaining that we're 
> doing this and thus "agent" comprises both "client" and "server" would 
> be useful here.

Again, that sentence is there, no?


> 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.


> TB9. Is "Ruby" really a format?
> 
> in the same way the others are?  I think its inclusion doesn't help 
> clarity here.

OK (no strong opinion).

> TB10. Is "DOM" really a format?
> 
> This was raised before and Chris explained why it's sensible to include 
> DOM in this list but it's raised questions, most recently from Stuart, 
> so I say lose it.

OK (no strong opinion).


> 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.


> TB12. Lose first sentence of chapter 1
> 
> The one beginning "Identification is..."

(no opinion; I like the hook back to... er... the intro text
I thought it was harking to seems to be gone. Hmm...)

> 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.


> TB14. Number principles?
> 
> Obviously it's a good idea to address principles, and people will want 
> to use them for reference.  Does numbering them introduce fragility?  In 
> XML 1, well-formedness and valiidity constraints are given short names, 
> not numbers, which are subsequently used as hyperlink anchors.  So for 
> example principle 1 could have the ID "Use URIs"

OK.

> 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.
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.


> TB16. URI & reference
> 
> In point of fact since a URI reference optionally is relative and 
> optionally has a fragment identifier, there are naturally four classes 
> of things here.  I think we should name them, define them, and make it 
> handy for other people to use them.   Strawman language:
> 
> "A URI reference contains a URI, which may be relative or absolute, and 
> optionally has a trailing #-delimited fragment identifier.  Thus there 
> are four classes of identifier, all of which are URI References:
> 
> 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.

> 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.

> 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."


> TB17. URI Schemes, lead-in
> 
> The section needs an introductory section explaining that the URI scheme 
>   is expressed using a :-delimited prefix.

(no opinion)
 
> TB18. Defined term for "http:" URIs
> 
> We use these a lot and talk about them a lot, so let's bless some 
> generic term.  Why not just HTTP URI, or possibly HURI or hURI?

HTTP URI seems pretty self-evident.


> TB19. URI Schemes ordered list
> 
> This needs serious revision, and I'm not at all sure that an ordered 
> list is the right way to go.  It conflates specific remarks about hURIs 
> with discussions of temporal relations and social governance.  Perhaps 
> 1.2 could have some brief subsections?

yeah, I'm not sure just how to say that stuff either.

[I ran out of steam at this point.]

-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/

Received on Friday, 28 June 2002 03:46:37 UTC