Re: [admin] Tool choices for the Annotation WG

Hello,

On Fri, 26 Sep 2014 11:01:56 -0400
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.

Seems good to me.
 
> (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.

+1

> (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.

+1 for using Github. One thing I don't like in github issue, though, is
that comments are not displayed as trees, like in email. This can lead
to difficulties understanding the answers. I suggest that we use github
issues but do not hesitate to port discussion onto the mailing list.

> (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.

+0
The more integrated the tools are, the better. Since github
offers the possibility to assign, we can use it. But if experienced
people think interfacing with IRC is more convenient, I have no
problem.

Regards,

Maxence

Received on Monday, 29 September 2014 11:35:57 UTC