Florian’s Blog

I’ve just produced the Disposition of Comments for the Media Queries Level 4 specification. A DoC is a W3C document whose goal is to represent that a work-in-progress specification has been widely reviewed, not only by members of the working group who writes it, but also by other relevant working groups as well as by the general public, and that these comments have all been formally addressed. Having received many comments from a diverse audience, and having addressed them, is a a key part of going from an interesting idea to a world wide standard.

Just as when I prepared the last DoC for CSS-UI-3, or the one before, or the DoC for CSS-CONTAIN, it proved to be a useful exercise, beyond merely demonstrating wide review. Every time, I find relevant comments that had been made a long time ago, but had been forgotten before reaching a conclusion, sometimes after having been discussed for a while, sometime never having been noticed at all. Preparing a DoC gives us a chance to find and address these comments.

However, every time, one aspect of the DoC strikes me as odd and outdated.

The DoC is for a specific draft, traditionally a LCWD, the last one before publication as a Candidate Recommendation. This makes a lot of sense when drafts are made in private then revealed to the world, then we get comments and address them, and repeat.

However, we do all our work in public, and continuously take in comments from both members and the general public. We no longer have an LCWD under the new process. We are increasingly in a process where we publish early publish often.

Under such a process, the last draft before CR is likely to be barely different from the one before it, which will also be similar to the one before it, etc. Showing wide review of the last draft is not very useful. A well managed document will have received wide review spread over many iterations, but the last draft will most likely not have received a lot of comments, even if many people read it, since the issues will have been ironed out before we decide we’re ready to transition to CR.

Actually, if a document has been well handled under the new process, the last draft before CR should barely receive any comment, since everything that can reasonably be discovered other than by trying to implement and pass a test suite should have been addressed already.

In practice, I believe that most recent DoCs have integrated that, and often cover a period longer than just the last draft before CR. However, partly because of habits, and partly because of the tooling used to prepare these documents, they all claim to be about a particular draft.

That’s not helpful, and I think we should change that. Going forward, DoC should declare not which draft it covers, but which period of time, and give a short justification for the starting point.

I do not think it is particularly useful for the DoC to cover the early stages of a specification when the overall design is still in flux, as many comments are invalidated by large rewrites of important parts. Different specifications mature at different speeds, so I do not think there will be a universal answer for when DoCs should start. The FPWD is probably a good guideline, as it typically signals the point where there’s agreement in the Working Group about the general design and where we start ironing out the details.

As the W3C Process does not impose any particular form for these DoC, all we need to start is to agree to start writing DoC that way, and for tools like bikeshed and Lea’s (unnamed?) tool to support this new style.