Le 6 oct. 06 à 07:57, Ian Hickson a écrit :
On Thu, 5 Oct 2006 [EMAIL PROTECTED] 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 ***
