Re: [admin] Tool choices for the Annotation WG

My thoughts to get the ball rolling...

On Fri, Sep 26, 2014 at 8:01 AM, Frederick Hirsch <w3c@fjhirsch.com> wrote:

> (1) Source format
> I suggest we agree to use ReSpec [3] to author documents.
>

+1

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

+1


> (3) Issue Tracking
>
        • 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.
>

+1, however if you see something that you have a concern about, say
something ... even if you don't have a solution.  There's lots of hard
problems that won't have obvious answers, and we don't want to miss them!
While it's much better to have a proposal for people to react to, it
shouldn't get in the way of tracking issues.



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

+1 to NOT using Bugzilla.



> 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]
>

+0 to using Tracker.  The integration is nice, but the interface is ... not
the most modern or featureful.



> 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 to using Github issues, and especially when there's an IRC bot.  Keeping
the issues with the documents, and in a very public venue I think has
advantages.  The web UI is clear, and there's a zillion apps and other
integrated solutions available.
We use it extensively in this specification project:
https://github.com/IIIF/iiif.io/issues


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

Yes, we should trial this when we have something to really comment on.  I
suggest aiming to start with annotations on the released FPWD documents for
public feedback and non-issue comments.  (Though using github issues as an
annotation store would be a fun project ... any takers? :) )



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

Issues can be assigned to people in github and assigned a deadline (via a
milestone), so we /could/ use the issue tracker as an action tracker... but
I'm fine with Tracker for non-issue related actions.

Rob

-- 
Rob Sanderson
Technology Collaboration Facilitator
Digital Library Systems and Services
Stanford, CA 94305