RE: 13 Aug Arch Doc available for review (skw-...01)

Hi Dan,

> -----Original Message-----
> From: Dan Connolly [mailto:connolly@w3.org]
> Sent: 14 August 2002 19:31
> To: Stuart Williams
> Cc: 'Ian B. Jacobs'; www-tag@w3.org
> Subject: RE: 13 Aug Arch Doc available for review (skw-...01)
> 
> 
> On Wed, 2002-08-14 at 13:07, Williams, Stuart wrote:
> [...]
> > [skw-2002-08-14-01]
> > 
> [...]
> > My preference would be that we
> > pulled the reference material to the front of the document with
little/none
> > of the narrative that elaborates on a terse/crisp set of staments of
> > principle.
> 
> Could you be more specific/concrete about what you want this stuff
> up front to say?

Ok... so this is mostly a matter of style and tastes vary.... there is
likely no 'right' answer.

Early on in the life of the TAG you had spoken about the 1-pager on Web
Architecture, the 5-pager, the 5-sections/chapters, the 5 volumes.... well
you weren't particular about 5, but the thing that you described had a
fractal quality. I would like our document to exhibit some of those
qualities.

I would like someone to be able to read just the Introduction to our
document and to come away with an appreciation of Web Architecture. The
(current) title of the document is "Architectural Principles of the World
Wide Web". A question I would expect to be answered by the end of the
introduction is *what* those prinicples are. We have indicated that we aim
to minimalist in the sense of state some minimum number of
necessary/important/essential principles - so the list should not be
unmanagably large. I don't think we should be challenging our readers to
'weed' them out from a longer narrative. I think we should state them
together, up front near the beginning of the document and justify/motivate
them in the sequel.

Different people will approach our document with different intent. Some will
approach with a spirit of enquiry; Some to question/challenge whether they
share in whatever concensus the document represents; Some in search of an
authorative source to resolve an issue... thus spake the TAG. I think each
audience is better served by actually stating the architectural principles
near the front.

So... to be concrete:

I really like the Introduction - the one paragraph and an enumerated list of
3 items. I wouldn't place anything before that. 

I think I'd add an extra section to the introduction ahead of Chapter 1 and
maybe ahead of "Limitations of this document" that introduced the concept of
the principles of Web Architecture and simply catalogued them either
organised under the three sub-tiles of Identifiers, Formats, and Protocols
or in some (partial-) order of most to least fundemental... (although I
guess maybe agreeing such an ordering might be fraught and unnecessary). At
this point I would not decorate the principles with any more than a sentence
or two expressing its import or acknowledging controversy. But for the whole
section I would set up the promise of deeper motivation, justification,
explaination later in the document.

Of course for a highly linked hyper-text work, different readers can take
different paths and there is no single implicit linear path... but what
we're writing at the moment has the feel of a linear document, and I think
the Introduction should set it so that readers with different
interests/needs can readily develop different strategies for 'consuming' the
document.

BTW... the Abstract and the opening paragraph of the introduction speak of
'rules'. Rules have a tone of MUST comply, principles has a tone of 'strong
encouragement'. I prefer the latter and it might be better for the Abstract
and Introduction to avoid the word 'rule' if indeed what we intend to offer
is 'principles'. Hmmm... Wordnet offer a wider range of senses with some in
common between 'rule' and 'principle':

http://www.cogsci.princeton.edu/cgi-bin/webwn1.7.1?stage=1&word=rule
http://www.cogsci.princeton.edu/cgi-bin/webwn1.7.1?stage=1&word=principle

> I think the document has gone too far in the terseness direction.
> If the document doesn't motivate/justify the principles, it's
> of little value, to me.

I'm not suggesting that the priniciples go unmotivate/unjustified... only
that we present our 'conclusions' first (with forward pointers) and
justify/motivate them deeper in the document.

> > The other temptation would be to put a reference at the  back.... as a
> > recap/summary...
> 
> I can live with any sort of index at the back, but please
> let's not just state principles with no motivation.

I can live with it at the back too... but would prefer it at the front
(that's a preference don't read it as a demand).

As to stating principles without motivation there's different scopings here.
Locally in the introduction I don't think that would be bad... its stating
the conclusions first... it usually helps understanding an arguement or a
proof if you know what you are trying to establish, prove first... it helps
readers direct their attention to what most interests them. Globally, the
document does indeed need to justify/motivate/explain the principles it
espouses.

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

Stuart

Received on Thursday, 15 August 2002 05:39:32 UTC