Re: [admin] Tool choices for the Annotation WG

On September 26, 2014 at 8:02:48 AM, Frederick Hirsch (w3c@fjhirsch.com) wrote:

The Annotation WG will need to make a few decisions regarding the tools we use to do our work. We touched on this during our last teleconference but did not have time; a list discussion will be useful for this topic. 

We decided during the call to use github for document management [1], thanks to Ivan for subsequently setting this up [2]. 

There still remain some choices: 

1. Source format 
2. Comment management 
3 Issue tracking 
4. Action management 

(1) Source format 

I suggest we agree to use ReSpec [3] to author documents. ReSpec allows simple HTML5 authoring in conjunction with JavaScript libraries to automatically generate document boilerplate based on some simple JSON contained in the document source, it also takes care of styling, bibliography generation and other aspects, freeing the editors to focus on the content. There is no 'compile cycle’, refresh the browser to see updates. 

I highly recommend ReSpec and suggest we (i.e. editors) use it. I think it is important to use a common approach in the group so people can help each other out with a common basis. 

(2) Comment Management 

Clearly once we are able to use annotations to comment on drafts that should be very helpful. Until that point it is simplest to comment via email clearly referencing which document by URL, section/line/context etc. Sometimes diffs are appropriate. We may have to make sure we figure out how to snapshot annotations with versions of documents if we wish to keep a record. 
At the risk of mentioning something that is not fully baked yet, Herbert van de Sompel has recently restarted a discussion with Doug and Ted Guild at the W3 about potentially implementing their TimeGate service which would be quite helpful on the versioning side.  As (I understand) it would allow a memento style URL to lay over the current W3 specification version scheme.  That would make it easy for orphaned annotations (that refer to previous versions of a document and cannot via robust link anchoring be easily reattached) to be pointed at the version of the document active at the time they were created.



(3) Issue Tracking 

It is important to track issues so that we are sure we have addressed them properly, to record the satisfaction with the resolution by the submitter, and to know the status of the work (and readiness for advancement), to give a few reasons. 

A best practice when raising an issue is not simply to state the problem, but also to offer a proposed resolution, e.g. provide the following when raising an issue [4]: 

• Title - A short descriptive name for the issue 
• Description - A longer and complete description of the issue, state in terms of the documents 
• Justification - Why is this an issue? E.g., state an architectural concern, demonstrate an interop problem, explain a use case that isn't met 
• Target - What deliverable the issue is against. 
• Proposal - A reasonably complete proposal for how the issue should be addressed. 

Regardless of mechanism, I think we need to be careful how we state and describe issues for clarity and usefulness ,and also to offer proposals. 

There are a number of ways to manage issues, and the WG needs to decide [5]. Here is a short list: 

1. Bugzilla - this offers an interface that is way too complex, if you’ve used it you know we ignore most of the functionality. I argue strongly against this choice for this group. 

2. Tracker - this is a W3C tool that allows entering and reviewing issues, and offers the benefit of limited integration with IRC trackbot, also integrated with participant list. [6] 

3. Git issue management - this offers collaborative issue management with a number of features, including commit integration, labels, milestones etc [7]. Not sure how assigning issues will work for people in the WG that are not also on github. There is also a REST API [8]. There has been work to integrate this functionality into IRC as well, but that might require additional effort to make functional. 

(Annotations - once we have an annotation mechanism perhaps we can label a group of annotations as an issue, but it is not clear how much work it will be to associate an issue with people, resolutions etc. I think we need to make a choice from one of the other systems, at least to start and perhaps use a hybrid approach, we will have to figure this out later, we can start with annotations for informal commenting) 

I’ve used tracker extensively and am fine with it, as it is very simple. git issue management also offers benefits, I’ve personally never used it in practice. The WG should discuss on the list, perhaps reach a consensus. 

(4) Action management 

We need to be able to assign actions to people, preferably on IRC during a call, so we should be able to use the full WG participant list and be able to review assigned actions, mark them as pending review or closed, and associate notes with them. 

Tracker does all this very nicely, so I suggest we use it for this [6]. 

If you know of good alternatives please indicate on the list, but I’d prefer the simplicity of tracker unless there are good reasons for an alternative. 

Have I forgotten anything? Please discuss on the list, especially issue management. 

regards, Frederick 

Frederick Hirsch, Nokia 
Co-Chair W3C Web Annotation WG 
@fjhirsch 

[1] http://www.w3.org/2014/09/24-annotation-minutes.html#logistics 

[2] http://lists.w3.org/Archives/Public/public-annotation/2014Sep/0052.html 

[3] http://www.w3.org/respec/ 

[4] https://www.w3.org/2008/xmlsec/Group/Overview.html#issues (member only, sorry, that was then) 

[5] https://www.w3.org/wiki/Guide/GitHub#Should_we_use_GitHub_for_issue_management_too.3F 

[6] http://www.w3.org/2005/06/tracker/ 

[7] https://github.com/blog/831-issues-2-0-the-next-generation 

[8] https://developer.github.com/v3/issues/