Re: Gloss standard terminology for resource/representation (ISSUE-81 Change Proposal)

On Thu, 2010-04-08 at 00:35 -0700, Ian Hickson wrote:
> On Tue, Apr 6, 2010 at 9:57 AM, Dan Connolly <connolly@w3.org> wrote:
> > This is informed by discussion with lots of people, but nobody
> > else has looked at it, so it's just from me.
> 
> Would the following be an acceptable compromise?
> 
>   <p>What some specifications, in particular the HTTP and URI
>   specifications, refer to as a <i>representation</i> is referred to
>   in this specification as a <dfn title="">resource</dfn>.</p>

That's probably close enough, sure.

> Here are some specific concerns I had with the exact text you proposed:
>
> > The term resource is used to refer to what is sometimes called a representation
> 
> There are two ways to interpret this: as saying that the term
> "resource" sometimes is used in the manner that refers to
> representations, or as saying that the term "resource" is always used
> in that manner. Since not every occurrence of the word "resource"
> means "representation" in the HTML5 spec, I think it's important for
> readers unfamiliar with any of these terms to not confuse this
> sentence for a definition of "resource" but merely an indication that
> the word "representation" is not used.

That makes sense.


> > in protocol literature
> 
> I think this overstates the case. Unlike "Internet media type", which
> truly is unambiguously used in the sense of MIME type in almost any
> spec that doesn't need the term "media" to mean what CSS uses it to
> mean, "representation" used far less commonly, and the term "resource"
> is used in a manner that often can be interpreted both ways. (Even in
> HTML5, if you want to make the case that the word "resource" is used
> to mean what the HTTP specs take it to mean, it's not very hard to
> find a number of cases where that interpretation makes sense.) So I
> think it's better to focus on specific specs that use
> "representation".

Fine; I don't think "in protocol literature" adds anything.

> 
> > such as section 1.2.2
> 
> I try to avoid referencing specific section numbers because they
> change when the specs are updated, leading to extra editing work
> later.

The risk is pretty small in the case of a full Internet Standard.
My preference would be to elaborate the section reference
to 1.2.2.  Separating Identification from Interaction
rather than eliminating it.

But as the premise of this proposal is that a segment of
the audience is familiar with the URI spec, I don't think
a specific section reference is critical.

> > of [RFC3986].
> 
> The spec's style is to not use references in sentences but to use the
> colloquial names of the specifications and then have the reference
> after the sentence.

OK.


> > Where that specification speaks of a URI that identifies a resource whose state is communicated via a typed byte sequence called a representation, we simply say that a URL identifies a resource, which is a typed byte sequence; the indirection is not mentioned in this specification.
> 
> There's already a comment about the URI/URL terminology in the URL
> section; mentioning it here might just confuse matters further.
> 
> It's also not clear to me that the above sentence really clarifies
> anything. [...]

OK, yes, it is somewhat contrived.


-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/
gpg D3C2 887B 0F92 6005 C541  0875 0F91 96DE 6E52 C29E

Received on Monday, 12 April 2010 15:10:45 UTC