Request for editing guidance

[I originally sent this request to the chairs privately, but in the 
interests of transparency I'm reposting it more or less unchanged to the 
public-html list.]


I'm having trouble consistently applying the reasoning that is cited as 
supporting the various working group decisions.

So that we can keep the specification coherent, I feel it is important 
that decisions be applied consistently. For example, if we removed all the 
words with the letter "z" in one section, on the basis that the letter "z" 
is bad, then it would be inconsistent to not apply that rule to the rest 
of the spec, removing all the words with the letter "z".

The working group has decided to remove various sections, such as the 
microdata section, the ping="" section, the Atom conversion section, and 
so forth. I don't understand what decides what is in and what decides what 
is not. Each argument given as a reason to support removing one section 
equally applies to other sections that we're not removing. For example, <a 
itemprop=""> is modular and competes with RDFa, so we removed it; but <a 
rel=""> is equally modular and equally competes with RDFa, but we did not. 
Why not? ping="" is not yet widely implemented, so we removed it, but 
scoped="" is not widely implemented either, but we're not removing it. Why 
not? <aside> is being kept because complexity is the only thing that might 
result in it being removed, but ping="" is far simpler and was removed.

Could you please write a coherent statement of editing guidance that I can 
consistently apply to the spec to make it consistent with the working 
group decisions throughout?


[The above e-mail received one reply; I've included a response to the 
questions raised in that reply below. This further response did not 
receive a reply; without a technical reply to this thread, however, I am 
not able to coherently apply the working group decisions and thus am not 
able to fully perform my editing duties for the HTML5 spec.]


I do participate in the process: I've written a number of change 
proposals, commented on the polls as requested, participated in the 
discussions, tried to find coherent compromises with other working group 
participants... and it doesn't work. The chairs still make decisions that 
result in inconsistent edits.

I can't edit the spec if I'm going to be instructed to make edits that 
make the spec internally inconsistent, with sections left in or taken out 
apparently arbitrarily: I simply don't know how to edit the spec in this 
situation.

The "reasoning that is cited" mentioned earlier consists of:

http://lists.w3.org/Archives/Public/public-html/2010Mar/0132.html 
http://lists.w3.org/Archives/Public/public-html/2010Jan/att-0218/issue-76-decision.html 
http://lists.w3.org/Archives/Public/public-html/2010Jun/0000.html

It is very hard to draw any guidance from such procedure.

Other decisions have included these:

http://lists.w3.org/Archives/Public/public-html/2010Jun/0001.html
http://lists.w3.org/Archives/Public/public-html/2010Jun/0002.html
http://lists.w3.org/Archives/Public/public-html/2010Jun/0003.html

These are the most wishy-washy, non-committal, incomprehensible and 
non-general arguments I have ever seen in my specification editing career. 
I cannot make generalisations from these e-mails. It took me several very 
careful readings of the above decisions to even work out what the 
decisions were!

Just so we're clear, I'm not complaining that decisions are made to change 
the spec. I have no problem with that. My problem is that the decisions 
are either not consistent with each other or are not consistent in a 
manner that is clear to me, which means I am not able to apply them to the 
spec in a consistent manner.

If I'm to continue as editor, I need clear instructions that I can apply 
to the spec as a whole. Before, I was applying editing principles based on 
my own opinions of what makes the most sense, but clearly these are not 
the same as the chairs'. Therefore, I can't do that anymore while 
maintaining the spec's integrity. As more and more decisions are made that 
aren't consistent with each other or aren't applied consistently to the 
entire document, the spec gets less and less coherent.

Here are some concrete examples:

Bug 9835 says that the conclusion from 0001 above is that the paragraph 
containing the word "OCR" is to be removed from the spec.

Why not the paragraph immediately following it, which essentially says the 
same thing? Why not the sentence that says "Resources can load 
incrementally; user agents may opt to consider a resource "available" 
whenever enough data has been obtained to begin processing the resource."? 
Why not the sentence that says "User agents may allow users to view the 
video content in manners more suitable to the user (e.g. full-screen or in 
an independent resizable window)."? Why not the paragraph that says "In 
this context, user agents may represent area and img elements with no 
specified alt attributes, or whose alt attributes are the empty string or 
some other non-visible text, in a user-agent-defined fashion intended to 
indicate the lack of suitable author-provided text."?

These are all virtually identical: they provide UAs with explicit 
permission to do something that a strict reading of the spec might suggest 
to over-enthusiastic implementors is not allowed. I honestly can't tell 
from 0001 what the reason to remove the OCR paragraph is, except maybe a 
vague and unsupported reference to a "widespread" (but wrong, mind you) 
"belief that the text is 'not useful, confusing, and potentially 
harmful'", whose counter argument (that the text is an improvement over 
nothing) is described as lacking "evidence or rationale", despite it 
pretty being self-evident as far as I can tell.

Here's another concrete example:

0002 cited above and the microdata decision cited above put forward nearly 
identical arguments, yet reach diametrically opposite conclusions. Both 
microdata and <figure> have been specified, have rationale, have support 
from implementors and developers, have counter-proposals that are also 
specified (in the case of <figure>, HTML4+ARIA, in the case of 
microdata, RDFa), both could be specified in a modular fashion, though 
in both cases doing so results in a fractured language, both are 
intrinsically part of HTML though in both cases an argument could be made 
that it could be turned into a generic vocabulary, both are immature 
(<figure> even more so), and so on.  

Yet the chairs reached diametrically opposite conclusions, while citing 
these characteristics as being the reason for the conclusions.

Why?

Frankly the only reason I can see is the idea that within the 
self-selected group of vocal people who spoke up on the subjects, one had 
more people arguming in favour and one had more people arguing against. 
But if that is going to be the actual way we edit the spec, then we need 
to dispense with the ridiculously expensive and heavy-weight process we 
have now wherein we pretend that the chairs make a considered decision, 
and just have straw polls for anything anyone objects to. Such a decision 
mechanism will lead to a highly inconsistent, "compromise by committee" 
spec, and is not something I'm interested in participating in.

I hope, however, that that isn't the actual process that we are following. 
Certainly, in public the chairs have repeatedly said that that is not the 
process we are following, and that instead quality of arguments is what 
matters. I hope that there are underlying principles that I can 
consistently apply that I simply haven't been able to figure out.

What are they?

Other concrete examples:

Why is ping="" out but hidden="" in?
Why is microdata in its own draft but class="" not?
Why is postMessage() split out but showModalDialeg() not?
Why is the 2D context interface out but ApplicationCache not?

I feel like the W3C version of the HTML draft is turning into a block of 
Emmentaler. This opinion is especially reinforced by the way people keep 
e-mailing me to ask me why this or that section has been removed, to which 
I've ended up just answering "I don't know, but if you use the WHATWG 
version of the spec you won't have to worry about that". Since my name is 
the name on the draft, people assume I understand the decisions that went 
into the draft. If my name is to continue being on the draft, if I'm to 
continue editing the spec, then I need to understand these decisions.


So again I ask:

Could you please write a coherent statement of editing guidance that I can 
consistently apply to the spec to make it consistent with the working 
group decisions throughout?

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Received on Wednesday, 9 June 2010 02:22:04 UTC