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

On 08.04.2010 09:35, Ian Hickson wrote:
> ...
> 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.
> ...

If the term "resource" is used sometimes for "resource", and sometimes 
for "representation" then Dan's proposed text should be modified to 
address this.

Optimally, the spec wouldn't use the same term for different things.

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

That's a disservice to the reader.

If the spec isn't precise about the reference, the reader will either 
ignore the reference, or will have to locate the exact text him/herself. 
In the first case the reference isn't followed, in the second case 
you're wasting the reader's time by having to locate something again and 
again.

Also, when specs are updated, it's *usually* necessary to verify that 
all things that are referenced are actually still there, and say the 
same thing. For this work it is *essential* that the spec actually is 
clear about what particular thing is being referenced.

> ...

Best regards, Julian

Received on Thursday, 8 April 2010 08:41:01 UTC