Warning:
This wiki has been archived and is now read-only.

Main Page

From Spec Annotation Community Group
Jump to: navigation, search

The current W3C process for commenting on specifications is complicated and discouraging to users. Discovering previous comments is also challenging, and leads to lost time. It's also difficult for spec editors to matching out-of-band comments sent through email or issue-trackers to the spec itself. Having an annotation sidebar that lets users create, review, and resolve spec comments would make the workflow much easier.

For the past several months, the WebPlatform.org team has been working to integrate the Annotator project to allow spec annotations, and it is ready for experimental use for W3C working groups. The Spec Annotation Community Group will collect use cases and requirements, feature requests, and bug reports, and will help coordinate feature implementation and bug fixes as well as integration with other open annotation systems.

This group will not publish specifications.

Links

  • Enabling Annotations on a Spec: How editors and groups can allow spec annotations
  • Scenarios: Different scenarios and issues for spec annotation
  • Workflows: Comparison and contrast of methods for spec feedback; traditional email feedback vs. annotations

Background

W3C recently launched the Web Annotation Working Group. The Web Annotation WG 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 the Web Annotation WG's own dogfood
    • using data model for interchange
    • experimenting with HTTP APIs
    • experimenting with federation, syndication, and aggregation

W3C, the WebPlatform project, 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

Initial 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, we've formed this dedicated W3C Spec Annotation Community Group.

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

Retrieved from "https://www.w3.org/community/spec-annotation/wiki/index.php?title=Main_Page&oldid=18"