- From: Ian Hickson <ian@hixie.ch>
- Date: Thu, 10 Nov 2005 19:24:31 +0000 (UTC)
- To: www-archive@w3.org
The CSS working group worked with a team of editors who sent comments on
one of our specifications. Included below is the feedback I sent on the
editorial comments. It is hoped that this may help others in future.
* In general it is much more helpful (to me at least) to get comments
in the form of plain-text e-mails, as opposed to inline edits and/or
Word documents. (I understand that it was easier to get the comments
in this form at short notice, I raise this merely as a general rule
of thumb for future work.)
* In general it is highly undesirable to change specification text,
because doing so almost invariably introduces mistakes. Often the exact
text in a spec is the result of hours of discussion and compromises,
the reasoning for which is often not included in the spec. Even moving
a single comma can be the difference between a browser complying to and
a browser violating the spec. Therefore, editorial changes should if
possible be limited to places where there are clear mistakes, as
opposed to places where changes may result in minor improvements to
readability.
For this reason, places where it was not immediately clear that the
suggestion was a substantial improvement were mostly left unchanged.
* An example of important punctuation: in CSS, the term "inline-block"
means something very different from the term "inline block". They are
not interchangeable.
* Some edits that could not be made are the kind that change:
"X is a chain of one or more Y"
...to:
"X is a chain of Y"
These edit cannot be made because the suggested new text, despite being
easier to read, is not as specific. It doesn't say whether a chain is
zero or more, one or more, or two or more items (all of which would be
valid interpretations, and all of which have very different results).
* Similarly, splitting up sentences can be dangerous. For example,
changing:
"X is a Y that Z"
...to:
"X is a Y. That Y is Z."
...results in a sentence that is much harder to argue about. People
often take sentences out of context then claim that they back up their
opinion, ignoring the following sentence that contradicts them. By
keeping all the pertinent information in a single sentence, many such
misunderstandings are avoided.
* Another kind of change to avoid is eliding deliberately vague text
("could be", "might look like") in favour of assertive text ("is").
This is a bad idea because it causes numerous issues to be raised
saying "but that's not the only way it is" -- sometimes, it is better
to be vague.
* I was unable to make many of the suggested edits because many of the
problems highlighted, for example use of "etc" in the second paragraph
of the abstract, are the result of compromises reached after painfully
long discussions.
This also applies to the suggestion of changing:
That is, given an element and a selector, this specification
defines whether that element matches the selector.
...to:
This specification defines whether an element matches a selector.
The current wording is the result of a long argument within the W3C
regarding what the input to a Selector is -- the sentence as currently
written states what is given, whereas the suggested sentence does not
(and could be interpreted to mean that the input is an XML document).
Similarly, one of the suggested changes in the abstract (removing "for
instance") couldn't be made because removing it would be interpreted
as implying that only the two options listed are possible, and that
other uses are not legitimate.
* One of the changes suggested replacing "doesn't expect ... will have
to implement" with "expects ... may not have to implement". This change
introduces the word "may", which, along with "must", "shall",
"optional", "recommended" and "required", have very special meanings
in specifications. See RFC2119 for details. The change here could not
be made because the suggested wording change would _substantially_
change the conformance requirements of implementations (effectively
allowing any implementation to remain conformant while not supporting
the specification).
Another change was the opposite, replacing "X may be Y" with "Do Y
to X". This removes a "may", changing the normative meaning of the
specification (and in this case, effectively meaning that despite
the specification saying that one should do Y, it would still be
non-conformant to do so).
* Another change that affects conformance is changing things like
X must be dropped.
...to
Drop X.
This change cannot be made because the word "must" has special meaning
in terms of conformance criteria. See RFC2119 for details.
* Similarly, the word "note" is given special meaning (it means that
the paragraph is non-normative) and therefore suggestions to reword
the document that remove the word "note" from the start of a paragraph
cannot be made.
* Some edits in the status section could not be made as they
represent boiler-plate text that we are forced to include.
* In CSS the typographical conventions are that CSS code in the body
text should be surrounded by single quotes, and attribute names in
double quotes.
* In specifications quotation marks never include the punctuation
unless that punctuation is actually part of the quoted string.
* Unicode codepoints: There is a table of these, it's the Unicode
database. The problem is that people disagree on what codepoint is
meant when a character is mentioned, which is why specifications
should generally be explicit and always include the codepoint number
when referring to the character. The error is not giving a codepoint
value at all. I've tried to fix those cases.
--
Ian Hickson U+1047E )\._.,--....,'``. fL
http://ln.hixie.ch/ U+263A /, _.. \ _\ ;`._ ,.
Things that are impossible just take longer. `._.-(,_..'--(,_..'`-.;.'
Received on Thursday, 10 November 2005 19:24:48 UTC