Re: Spec with issue markers [was: Re: HTML5-warnings - request to publish as next heartbeat WD]

Quoting James Graham <jgraham@opera.com>:

> Jonas Sicking wrote:
>>> A copy of the spec with the WHATWG annotations in is at [1] (that   
>>> URL is not
>>> expected to be long-lasting). Note how this document makes the relative
>>> maturity of the <iframe> ("working draft") and <video> ("last call for
>>> comments") sections clear. I understand that some people will think that
>>> reusing W3C language is inappropriate; that can be changed. Please bear in
>>> mind that this document may contain errors since my   
>>> spec-processing pipeline
>>> is immature; indeed I spotted some encoding issues already.
>>
>> Wow, this is great! I'd say I'd even prefer even more attention to the
>> status annotations, i.e. give them a border or something else to make
>> them stand out.
>
> OK I will experiment with making the markers more obvious.
>
> Another idea to throw into the ring is that it would be possible to add
> information to the annotations file about whether a section has an
> associated tracker issue. That would allow a link to the issue to be
> automatically inserted into the status marker along with, possibly,
> some explanatory text about the fact that the issue must be resolved
> before the next spec phase transition. Obviously some UI to maintain
> the list of issues in the annotations file would be needed but that is
> a solvable problem.

I now have a version of the spec with links to open ISSUEs [1]. See  
[2] for an example of a section where it applies. The issues are added  
using an extra metadata file that contains a map between each issue  
and one or more sections in the spec. The file I have created so far  
is at [3]; it contains mappings for open issues which map well on to  
specific sections of the spec (it is hard to see how to associate  
ISSUE-59 with the spec since it is about the language reference;  
ISSUE-41 doesn't map on to a particular section of the spec except  
maybe microdata). I also just noticed that I missed ISSUE-55; that  
will be fixed. However this list is not supposed to be definitive it  
is just a quickly-knocked-together sample to demonstrate the approach.  
In particular raised issues are not covered at all. Also the use of  
class="XXX" and the resulting appearance is a result of doing the  
simplest thing that could possibly work rather than some commitment to  
having that exact appearance for the markers.

Note that I have not applied any date cut-off to the issues given  
markers; this is deliberate since the intent is to provide information  
about all the things that must be fixed before the next spec status  
transition not to single out "controversial" areas of the spec.

At this point it would be useful to get feedback. Is this something  
that people believe is worth pursuing? How should the issue to section  
map be maintained? Is there some style that would be better for the  
status/issue markers?

(For the curious; this works by extending the annotation file format  
used by WHATWG by adding an extra status attribute on the root element  
indicating the status of the draft as a whole, and adding <issue  
name="" url=""/> elements to each <entry> with one more associated  
issues. I have a little bit of code that takes the file in [3] and  
mixes the information into a copy of the WHATWG annotation file. The  
resulting annotation file is then used with an anolis module to  
produce the actual specification. My anolis repository is at [4]; once  
I have cleaned up the code a bit I will talk to gsnedders about  
pushing this back to the main repository. The code to process the  
issue_markers file is at [5]. I also plan to add UI for the  
annotations feature to pimpmyspec.net.).

[1] http://hoppipolla.co.uk/410/spec-full.html
[2] http://hoppipolla.co.uk/410/spec-full.html#video
[3] http://hoppipolla.co.uk/410/issue_markers
[4] http://hg.hoppipolla.co.uk/anolis/
[5] http://hg.hoppipolla.co.uk/w3c_issues

Received on Tuesday, 18 August 2009 22:25:00 UTC