Spec Annotation

DRAFT

The Web Annotation WG has recently agreed to use annotation to get feedback on the group's specifications. This is an experiment, and not yet officially supported by W3C. This experiment is open to other working groups as well.

Providing a means to annotate specs serves 2 purposes:

1. providing a better means to get feedback from a wider audience than traditional approaches such as email or out-of-band issue-tracking systems
2. eating our own dogfood
   • using data model for interchange
   • experimenting with HTTP APIs
   • experimenting with federation, syndication, and aggregation

W3C and the Web Annotation Working Group invite all projects that provide annotation capabilities to join in this experiment.

WebPlatform.org Annotator

The WebPlatform.org project has been working on integrating the Annotator software into its systems, and is offering its use for annotating specifications. This implementation is provided by Hypothesis. The software consists of 2 main components:

1. a client-side JavaScript library, included in a specification by use of a 'script' element, which provides an annotation client
2. a server-side annotation storage repository, located at notes.webplatform.org

Client

• allows user to log into server-side account
• allows user to select a section of a spec (text, image), and create a new annotation, including relevant comments, tags, and links
• allows user to publish annotation to WebPlatform annotation server, marked as public or private
  • future enhancement: will allow the user to publish to multiple annotation repositories
• allows user to see public annotations (and authorized private annotations) related to this specification in a sidebar
  • future enhancement: will allow annotations to be organized into channels with different permission levels
• anchors comments to specific selected passages
• allows user to filter annotations based on tags and other criteria

Server

• allows users to create an account
• allows authorized users to publish annotations from the dedicated script-based annotation client
  • future enhancement: will allow users to publish annotation from different annotation clients
• allows user to search and filter annotations based on specification URL, tags, author, and other criteria
• future enhancement: will allow users to share (syndicate/federate) annotations from other annotation servers

Requirements

• Data Model:
  • SHOULD use Web Annotation Data Model for interchange in early phases of deployment (e.g. while spec is in FPWD)
  • MAY use Open Annotation Data Model
  • MUST use Web Annotation Data Model for interchange by spec's Candidate Recommendation phase (at latest)
• SHOULD use HTTP REST API for publication (client and server)
• MUST use Web Annotation Robust Anchoring API for selectors by that spec's Candidate Recommendation phase (client)
• MUST be browser-based (JavaScript) for dedicated client
• MUST archive annotations as emails to dedicated list

Phases

1. start with browser-based JavaScript UI client and dedicated repository, provided by WebPlatform.org
2. enhance client to allow annotations to be published on different repositories
3. enhance server to allow annotations to published from other annotation clients
4. enhance server to allow annotations to be shared to other services and to aggregate spec annotations from other services
5. enhance server and client to allow different "channels" with different permission levels

Oversight, Feedback, and Development

In order to provide a dedicated forum for discussion of use cases, requirements, features, development, maintenance, bug requests, and so on, in a way that doesn't distract the specification and standardization work going on in the Web Annotation WG, a dedicated W3C Specification Annotation Community Group should be formed.

All comments and questions about the annotation service should be directed to this CG.