Categories
HTML5 Specs W3C

How to comment and when

The most important point to remember during the review is to make sure you’re reviewing the correct document. You’ll want to review the W3C version of the HTML5 specification. Though the WhatWG group maintains a document that is frequently referred to as HTML5, it isn’t comparable to the W3C version of the document, as it does differ from the official W3C version of the HTML5 spec.

The IE Blog mentioned about making comments in the public-html-comments email list. This list is open to everyone, and you don’t have to be a member of the W3C or the HTML WG to send an email or subscribe to this email list. However, if you want your concern addressed within the HTML WG Decision Process, you’ll need to file a bug and do so before October 1st.

Prior to October 1st: Filing Bugs

If you find an error or want to submit a recommended change, and it’s before October 1st, you’re better off filing a bug against the specification. You don’t have to be a member of the W3C or HTML WG in order to file a bug. It’s easy and quick to create a Bugzilla account.

When you do file a bug against the HTML5 specification, make sure you file it against the HTML WG Product. When the bug entry page opens, select “HTML5 Spec (editor: Ian Hickson)” from the Components listed in the page. You can also file bugs against other components, but I’m focusing just on the HTML5 spec in this guide.

You should search through the bugs, first, to see if a bug has already been filed on the error you’re reporting, or the change you’re requesting. No worries, though, if you miss some bugs and end up filing a duplicate: someone will note that it is a duplicate, and process the bug, accordingly.

Provide as much information as you can. Try to be concise, but thorough. The fields you should focus on are the Summary field and the Description. The Summary is a title for the bug and the Description provides the details. You don’t want to change any of the drop-down values and you should be automatically added to the cc list for the bug.

If the bug is non-editorial—not related to fixing an error, including typographical errors—you’ll want to add the NE (Not Editorial) keyword to the keywords field. Adding this keyword also ensures that a copy of the bug is sent to the HTML WG members. If in doubt, leave off the keyword—it will be added by others at a later time. Also add other keywords as you deem appropriate. (Clicking on the Keyword label opens a page with the available keywords.)

If you’re new to filing bugs, there are bug writing guidelines.

Your bug could trigger a lively debate in the bug comments. Don’t be intimidated by the debate. Do join if if you think your doing so helps in determining how the bug is resolved. Don’t join in just to repeat your arguments over and over again, no matter how provoked. No one has ever been impressed with anyone because of what they say in a bug, so don’t try to impress anyone—communicate simply, cleanly, and succinctly.

The editor may not understand what you’re asking and ask for more information. If he does, provide the additional information, or ask him for clarification about what he needs. Don’t expect an immediate response. Some bugs have taken months to be resolved. However, with the new LC timeline, all bugs should be addressed by December.

If the editor agrees with you and modifies the HTML5 specification in order to resolve the bug, review the fix, and signal that you’re you’re happy with it by closing the bug. If you don’t agree with the fix, or if the editor marks the bug as WONTFIX, you have another option: escalate the bug to an issue. You do this by adding the TrackerRequest keyword to the bug. Eventually, the TrackerRequest keyword is changed to TrackerIssue and an issue number assigned.

If you’re following a bug but are not the reporter, and the editor resolves the bug and you’re not happy, you can also trigger a TrackerRequest. You don’t have to be the bug reporter in order to escalate the bug to an issue.

What happens with issues at this point gets a little tricky.

Once an Issue has been raised

Once a bug has been raised to an issue via TrackerRequest in the bug database, it’s made into an issue. All bugs entered into the database before October 1st that end up as issues enter the HTML WG Decision Process. The first phase in the process is to file a Change Proposal for the bug.

Technically, you don’t have to be a member of the HTML WG in order to file a Change Proposal. All you need do is grant ownership of the copyright of your proposal to the W3C and agree to the W3C patent policy. A procedure I’d recommend is to send the Change Proposal as an email to public-html-comments, copy the copyright grant and patent acknowledgment to the end of the proposal, and notify the HTML WG co-chairs of the Change Proposal. You should then be in compliance with the HTML WG Decision Process.

However, filing a Change Proposal when you’re not a member has never been tested, and when I attempted to do so, I received some strong push back. I still think it is a viable approach, but be forewarned that the HTML WG co-chairs may get bitchy about the whole thing. You might be better off just joining the HTML WG. Unless you work for a W3C member, you can easily join the group as an Invited Expert and it doesn’t cost you a penny.

The co-chairs will call for a counter-proposal once you’ve filed your change proposal. If none is filed, the co-chairs will ask for a Call for Consensus on the proposal. If counter or alternative proposals are filed, the co-chairs will make a decision based on all of the proposals—the new Last Call timeline does not include any time for surveys. If you disagree with the decision, and you feel strongly about the issue, file a Formal Objection, covered later.

Filing a Bug after October 1st and Last Call Comments

Bugs filed after October 1st are handled differently. Instead of going through the bug/issue/decision process, the bug is automatically labeled a Last Call comment.

A Last Call comment is equivalent to a working group issue but without the formal change proposal/counter proposal. LC Comments have to be resolved in some way in the working group before the specification can proceed to the next state.

You can also post LC comments to public-html-comments but you might want to make a note in the subject line that you want the comment to be treated as a Last Call comment—or otherwise designate that the comment as something that requires an HTML WG response. So that LC comments sent to public-html-comments can be referenced with a specific identifier and tracked, they will be entered into the bug or issues database.

What Should you say, and how should you say it

The HTML WG may end up with a Last Call comment template, similar to what’s provided for change proposals. Generally, though, there’s a couple of things to keep in mind when writing your comment.

The HTML WG and the HTML WG co-chairs (not to mention the W3C team rep, contact, and Director) want technical discussions. They like technical discussions. Social discussions, or discussions that border on anything related to beliefs, feelings, or global goodness leaves them cold, which then leaves your requested change out in the cold. This means you should word your concerns using technical terms as much as possible and, if relevant to your concern, provide a technical solution.

You don’t have to write a book. In fact, assume that the HTML WG has exactly five minutes to devote to your comment or change proposal, so cover the important bits and leave your inner James Joyce at home.

If your comment or proposal generates discussion, do participate, but do so carefully. There are discussion guidelines for all email groups within the W3C, and there’s an additional Discussion guideline for the HTML WG. To rephrase what the guidelines say:

Participate, but if you find yourself repeating what you’ve said earlier, then stop. And if people disagree with you and you don’t have anything new to add in response, just thank the person, say you disagree, and let it go.

Use a neutral tone of voice. This is tough, because we all know that we’re right and those idiots are wrong. But pretend those idiots are your beloved, white haired old granny, who would be horribly hurt if you responded the way you would like to respond. So treat the idiots kindly and respectfully. If nothing else, a calm, measured response will drive them crazy.

And now, I want to tell you about the wild squash plant in my garden. No, not really. Now I want to mention how you have to stay on topic in the discussions. If you don’t, the co-chairs, otherwise collectively known as “Dad”, will send you a “tut tut” email. This email is going to irritate the hell out of you—so stay on topic.

Of course, I’m one to give advice, considering that I have had some significant difficulties with members of the HTML WG. All I’ll say is that I’m not completely to blame for the problems but I’m not blameless, either, which is usually the way these things go.

For one, I was overly persistent—getting my teeth into something and not letting it go, long past the point when anything useful could be dragged from the discussion. It was bad enough if the topic was technical in nature, but I would also do so about group procedures, and this was the equivalent to fingernails on a chalk board for some in the group.

In addition, I can be a bit of a know-it-all in the discussions. There’s a fine line between being confident of your viewpoint, and being arrogant, sarcastic, or pedantic, and I crossed this line more than once. Sometimes I did so unknowingly; other times, because I was angry or frustrated, or was responding to what I perceived to be know-it-all behavior in others. Regardless of reason, it’s not an effective communication technique.

If you do participate in a debate about your comments or change proposals in the mailing lists, and you recognize both behaviors in others or yourself, just stop. And if you do find yourself getting pissed, walk away. You’ll live longer, and your cat won’t be afraid of you.

Formal Objections

Hopefully, in all of the proposal, counter-proposal, LC comments, and related discussions, decisions will get made most people can live with and the HTML5 specification will progress. Since much of the document has no independent implementations, the W3C will most likely make a call for implementations. During the implementation phase, more problems may be discovered, and there will be additional time for reviewing or filing bugs.

If you find, though, that there was a decision you can’t live with, you do have one final option: file a Formal Objection. A Formal Objection is the procedural equivalent of a missing end tag in an XHTML document: it generates a draconian response. Formal Objections go the Director, otherwise known as Sir Tim Berners-Lee. Sir Tim invented the inter-web tube thing. Sir Tim is a very busy man. I also have the impression that he doesn’t suffer fools gladly. If you’re going to file a Formal Objection, you better make sure you know what you’re doing, and follow the procedure for Formal Objections exactly.

Ah, but we all know that the community interested in HTML5 is an easy going cooperative group, so why worry about things like Formal Objections?

OK, enough with procedures: let’s get onto the document.