Keeping a document that shows the current status quo

One of the best decisions I made when I began to work as an editor on XSD 1.1 was the decision to attempt, always, to ensure that decisions made by the WG during a telcon were reflected before the next WG meeting — and preferably before close of business that same day — in a copy of the spec kept in a stable location. This has turned out, I think, to be a useful technique.

I didn’t always feel this way. In 1997 it irritated me profoundly that Dan Connolly used to complain whenever there were decisions the XML working group had made that he didn’t see reflected in the most recent draft of the XML spec he could find. But while I’m still not sure I think his reasons were sound, I have come to believe that his conclusion was correct. (Maybe I didn’t understand his reasons propertly.)

• It makes it easier for WG members to see where we are.

It makes it easier for other WGs, too, although other WGs seem unaccountably leery of looking at the current status quo document instead of at public working drafts on the /TR page. I suppose they feel justifiably that there can be such a thing as Too Much Information.

• It means that WG decisions have visible effects immediately (or, as immediately as is compatible with my having to regenerate the spec and check in the new copies, when tends to take a few hours), which is good for morale.

I at least find it alienating and depressing to work hard making decisions in a WG and find, months later, that the editors have still not gotten around to making the text of the spec reflect those decisions. Experience also shows that if much time elapses between decision and revision of the spec, the editors end up forgetting what the WG decided, or conveniently rewriting it in their memory.

• Constant re-publication (even if it’s only in the member-only portion of the site) also helps keep the document production system in good trim. Problems get found and fixed sooner, and debugging is simpler: fewer problems around means it’s less likely that one problem will be interacting with or masking another.
• Constant re-publication (even if it’s only in the member-only portion of the site) also helps keep the document in good trim. If I link-check and validate the status quo regularly, publishing a working draft becomes a simple task instead of requiring herculean efforts to fix HTML- and link-validity errors.

We haven’t always managed to achieve the same-day goal; sometimes the spec gets a week, or two weeks, out of date. And on a couple of occasions when outside circumstances were unfavorable, the Structures spec got as much as four months out of date. Bringing the status-quo documents up to date after that kind of interval was a nightmare — a suitable punishment, perhaps, for letting them get so far out of date in the first place.

Bugzilla as issue tracking system

Keeping the issues list up to date has many of the same advantages, although as a WG we have not been nearly so good about that as about keeping the ‘current editors’ copy’ of the spec up to date. And of course, like many working groups we have trouble providing quick response. Most of the bugs we fixed today were reported months ago, some, well, longer ago than that. We need to do better about that; it would help keep the number of issues from climbing so high in the first place.

And if being slow to get back to the reader has a bad effect on the WG’s relation to the wider community, being slow to update the status of issues, once the WG acts on them, has an even worse effect on the WG’s relation with itself. When the issues list is out of date, you can’t look at any issue without the risk that you’re wasting time re-considering something the WG actually already decided once. Or, just as likely, you risk the WG saying “Wait, we don’t need to look at this one, we did it a few months ago” when what they remember is that it was discussed a few months ago, without remembering that it was not resolved a few months ago.

So I have come to believe it’s very helpful to get the issues list updated right away after a meeting. Or preferably during the meeting, but the XML Schema WG has never quite assimilated that idea.

For a long time, we maintained our issues list in XML, using a series of ad hoc vocabularies. Because they were in XML, it was possible to do a lot of nifty things with them; we had stylesheets to indicate status via foreground and background color, we had a good fit between the data and the information we want to maintain about issues, and so on.

But maintaining the issues list in an XML document on the server meant that only WG members with CVS access could update it. And keeping the list in a single XML document meant, in practice, that only one person at a time could (or maybe I mean would) do so. And that person invariably became a bottleneck.

Bugzilla is not well suited to the task of of issue tracking for a working group developing a spec. It’s designed for tracking software bugs, not design issues or spec defect reports; its workflow doesn’t match what any of my WGs does; its terminology is sub-optimal; its notion of text has all the power and charm of ASCII email (which is particularly grating for WGs working with XML technology: we know how much better things can be with good markup!).

But it’s got a convenient Web interface and more than one WG member can be updating things at a time. And I have come to believe that those two facts trump all others. Someday I’ll get around to designing and implementing an XML-based issue tracking system for working groups; it will have a Web interface and suitable markup, and it will be fun to develop.

In the meantime, we use Bugzilla.

So it was with Bugzilla that I spent most of my afternoon, while make and XSLT and CVS checkins went on in the background.

Marking an issue resolved can take time. Since the status-quo version of the spec is not publicly accessible, whenever the comment came from someone outside the WG who doesn’t have member access to the W3C site it’s necessary to transcribe the wording we finally adopted into the bug record, so the originator of the comment actually has a way to tell whether we got it fixed or not. And if the bug applies both to XSD 1.0 and to XSD 1.1, our decision today resolves it only for the latter, so a new issue needs to be raised for 1.0, otherwise we’ll lose track of it.

Two pieces of advice, then, for those using Bugzilla to maintain issues lists:

• Learn to use the “Change several bugs at once” feature.
• Learn to use the “Clone this bug” feature.

Enough said.

There’s a final reason that marking issues resolved can be slow going. Because these are Last-Call comments, the working group is responsible for keeping an audit trail to show that all comments have been dealt with, and to document that each person who raised an issue has been asked explicitly whether the WG’s action on the issue has satisfied their concerns.

If they’re not satisfied, the director of the consortium reviews the question when the time comes to move the spec forward. Woe then to the working group who didn’t make an effort to satisfy those who commented on its drafts. If the chair, or the staff contact, can explain plausibly what point is at issue and what the WG has done to try to accommodate the reader who raised the issue and why it’s not possible to do anything more to resolve the comment without breaking something more important, then the director may well sustain the WG in its decision. I’ve seen that happen.

But when the working group did not in fact try very hard to resolve the comment, and all you have to say is “well, we didn’t want to do that”, or “no, we didn’t want to consider that”, then you’re in for a long afternoon of sharp, skeptical questions and there’s a real possibility that the spec will be sent back to the working group so that more time can be spent resolving the open points of dispute. I’ve seen that happen, too.

It’s hard for some WGs to remember, but the goal is not to achieve consensus within the working group. The goal is to achieve consensus within the Web community as a whole.

And that, in the end, is what the whole exercise is about.