Re: Resources and URIs

Roy T. Fielding said:
>>> It really would be most constructive if you'd suggest
>>> alternative text for the spec.
>> Look, this is like God asking me to tell him what 'thou shalt not' 
>> means. How the hell do I know what text to suggest? I didnt invent the 
>> Web.  Here's the group, tasked with the job of writing the document 
>> which is supposed to define the basic terminology, and they want ME to 
>> tell them what they are talking about? That is crazy. [later: but see 
>> PS.]
> No, we want you to put up or shut up.  We want you to take the time to
> describe what it is you want the definition to say, because it is quite
> possible that you might come up with better wording than what we have 
> now.
> That is standard operating procedure for editing specifications.

Wrong. Wrong wrong wrong wrong wrong.

When someone says "that wording has says it wrongly", it's reasonable to
say "put up or shut up". But when someone says "I don't understand the
concept that wording is trying to express", it isn't. *Nobody* can write
better words if they don't understand the concept, but that doesn't make
the present words right just because of that.

The specification should be a black box that makes sense without knowing
what's going on inside it. If an internal detail matters, it needs to be
made explicit.

--------

Concrete example: earlier versions of the NNTP specification read:

    MODE READER SHOULD be used by the client to indicate to the server
    that it is a newsreading client.

Nowhere does it say what a newsreading client is, or why a client would
want to be one, or even why it would *not* want to be one. All the server
authors seemed to know what this command was for and why, but could I
get a coherent explanation out of them? They were too close to the
problem. Saying "put up or shut up" to me wouldn't help: I couldn't put
up because I didn't know what was going on, and I wouldn't shut up
because I could see the problem. I suggested:

    MODE READER MUST be sent as the first command.

only to be told that no, sometimes it's very important that you *don't*
send the command. That left me even more confused.

Only after a long thread rather reminiscent of this one did I finally get
an explanation that made sense. *Then* I was able to propose new wording,
which got kicked around a fair while. And now we have something that makes
sense to someone reading the specification as a black box:

    MODE READER SHOULD be sent by any client that intends to use any
    command other than <list>. Servers [...] MAY reject such commands
    until after a MODE READER command has been sent.

The "secret" knowledge was that some servers have two different modes and
can't switch back once they've made the switch once.

--------

Right now you're in the position of the server author who knows all about
the internals. It may seem obvious to you that there are two modes and the
client needs to select one. But the other poster (sorry, I forget the name)
is standing there saying "Why should clients issue this command? What's the
point?" He can't suggest a better way to say things because you haven't
explained things well enough for him to understand them!

-- 
Clive D.W. Feather  | Work:  <clive@demon.net>   | Tel:    +44 20 8495 6138
Internet Expert     | Home:  <clive@davros.org>  | *** NOTE CHANGE ***
Demon Internet      | WWW: http://www.davros.org | Fax:    +44 870 051 9937
Thus plc            |                            | Mobile: +44 7973 377646

Received on Thursday, 24 April 2003 02:06:17 UTC