Re: [XBL] XBL 2.0 Introduction

Le 6 oct. 06 à 07:57, Ian Hickson a écrit :
> On Thu, 5 Oct 2006 karl@w3.org wrote:
>>
>> About http://www.w3.org/TR/2006/WD-xbl-20060907/#introduction
>>
>> Do not start the first sentence by "This specification".
>
> Why not? It is far easier to rename a specification or to move content
> between specifications when the name of the specification isn't  
> mentioned
> anywhere in the body.

The reasoning is that the topic of the document is not the document  
itself but the technology. It is a bit like (stretching a metaphor),  
you were reading a novel and it would say "This novel tells you a  
story about" or a movie on screen starting with "In this movie, you  
will see". It is plainly stylistic.
I will not push the issue further, but it is a reminder when writing  
specification.
Talk about the technology, not the spec.

>> See comment about "abstract".
>
> The comment about the abstract didn't explain why "This  
> specification" was
> bad. I agree that "This specification" is bad in an abstract,  
> because an
> abstract is supposed to be context insensitive. However this  
> doesn't apply
> to the introduction.

see above.

>> What is the semantics of the doubled line on the left? Is it an  
>> example?
>> Is it a note? Maybe that would be good to explain or contextualize  
>> a bit
>> more.
>
> The presence of the doubled line on the left depends entirely on what
> stylesheet you are using. The text in the spec implies that the  
> paragraphs
> in the doubled line are part of the first example; this seems pretty
> clear. I'm not sure how it could be explained without alienating  
> people
> who are not using the same stylesheet.

In some parts of the document, it starts with "For example" which is  
fine for the readers. But In the introduction it is not necessary  
clear where the examples stop.  At least there are clearly marked in  
the markup with class="example", though it doesn't necessary help the  
reader.

> In conclusion, I disagree with the suggestions made in this e-mail.  
> Please
> let me know if you disagree with my disagreement so that I may clearly
> mark this in the disposition of comments.

I can't think of an easy solution so far for it given your answer,  
but let's agree with you.
answer accepted.

Thanks

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Friday, 6 October 2006 01:23:09 UTC