WebPlatform Notes

a Specification Annotation Tool

The spec annotation tool is an experiment by the WebPlatform.org team and partners to make it easier for the average developer or designer to provide important feedback to technical specifications, and for working groups to discuss and process that feedback.

You can check out the live stream of annotations being made on specs right now.

This page contains general information about using the spec annotation tool found on some W3C specs. If it does not answer your questions, please post on the public-spec-annotation-help@w3.org mailing list (archive). Or, you can feel free to annotate this page so that we can improve the documentation.

For general information about the tool, please visit the Spec Annotation Community Group, where you can read more about the details and roadmap for the project, join the CG, request features, or learn how to get involved in helping improve the annotation tool. You can also file issues on our Gihub account, WebPlatform/annotation-service.

The spec annotation tool is currently available on selected specs located on W3.org and Specs.WebPlatform.org. Annotations are visible in the sidebar of the specs or on the Notes.WebPlatform.org site, and are archived on the spec's dedicated mailing list.

Getting Started

Opening the sidebar:

If you’re on a supported spec, you will see a small “comment” icon on the upper right, near the scrollbar. To open the annotation sidebar, simply click on this button. To close it, click on it again or click anywhere on the page outside of the sidebar.

open sidebar

Creating an account:

Important: Though you may be annotating a spec at W3.org, the annotation service does not use W3C login information. Please use your WebPlatform.org login credentials instead.

From the sidebar:

Click “Sign in”, and a login dialog will open. Click on the “Create an account” link to create an account. When you receive the confirmation email, click the link inside. You are now ready to annotate.

sign-in dialog

From WebPlatform.org:

You can create an account directly on accounts.WebPlatform.org.

If you already have an account on WebPlatform.org, you should be able to sign in without creating a new account.

Forgotten Password?

Click “Forgot password?” on the sign-in dialog and enter the email address you signed up for your account with.
sign-in dialog

Enter the email address you signed up for your account with.
reset password dialog

An email will be sent to you. Click “Reset password”. Enter the new password for your account. Click sign in, and your password will be reset.

Making annotations:

Creating an annotation

To create an annotation select the text you want and click on the pen icon.

selection

The side bar will open and you’ll be able to add text and tags. You can use markdown to attach links and pictures to your annotations. You can learn more about markdown here.
annotating

Public vs Private Annotations

You can set your annotations to be publicly visible, or private. Private annotations are visible only to you. You can change this setting this when you create or edit an annotation.

By default, annotations are public, so that your annotations can be seen by the working group. If you want to keep your annotations to yourself, please change this setting before publishing your annotation. You can change your private annotations to public by editing your annotation.

visibility

A future “groups” feature is planned that will let you share your annotations with a set of people of your choice, such as other participants in a working group, co-workers, or a specific community.

Tagging

Tagging your annotations is very important. This helps the working group prioritize and process your comment, and for people to search and filter annotations based on different criteria. Please use the following tags:

Editing an annotation

To edit an annotation, simply hover over the annotation card and select the edit button.
edit

Replying to an annotation

To reply to an annotation, hover over the annotation card and select reply.

Deleting annotations

To delete an annotation, hover over the corresponding annotation card and select delete.
delete
Note: if your annotation has been replied to, it can still be deleted, but the comments of people who replied to your annotation won’t be deleted. Instead a place holder card will replace the deleted annotation.

Accessing the control bar:

Roll over and hover on the speech bubble in the tool button.  A set of controls will drop down.  They are each turned off by default.

Show annotations

Clicking on the eye in controlbar menu renders all annotations and highlights visible in the page. Clicking on any highlight in the text, shows the annotation under the cursor at that spot.

show annotations

The highlight tool

To use the highlight tool, simply select it from the controlbar menu. To highlight something simply select text to create a new highlight (it’s that easy). Highlights default to private annotations, so they are only visible if you share the link to them.

If you click on a highlight it will show you the corresponding card in the sidebar. Likewise, hovering over an annotation card in the side bar will reveal the corresponding highlight in the document.

highlight
To turn highlighting mode off, simply select it again from the controlbar menu.

New Comment

This button creates a new unattached comment as opposed to a specific annotation. Comments are useful for general discussion about the topic of the article, without having to anchor it to a specific part of the text.

Viewing annotations:

The marker bar:

The marker bar, running alongside the scrollbar, shows you where annotations are on the page. Markers indicate clusters of one or more annotations. Click on a marker to open the sidebar and view the annotations. Click on an annotation to see its detail view.

heatmap

Click on the up marker and down marker to navigate to the previous and next annotations on the page.

navigation

Search/Filters

To use the search bar, enter some text and hit “enter”. You can search on specific criteria by using prefixes like “user:username” or “tag:sometag”.

magnify

Sort Controls

The sort control changes how the annotations are sorted. Currently you can sort annotations by location in document (i.e. they fall roughly where they lie in the text), newest, and oldest.
sort control

The Notes stream

In addition to viewing annotations in the sidebar of a spec, you can also view all annotations being made on any spec on the Notes.WebPlatform.org site. You can filter by tags, by users, by specs, or by keywords.

Commenting best practices

When leaving feedback on a specification, you should follow these basic guidelines:

Submitting feedback about this annotation service

Feel free to post questions, comments, or suggestions on the public-spec-annotation-help@w3.org mailing list.

About the WebPlatform project

WebPlatform.org is a community project, sponsored by the WebPlatform stewards/, and run by W3C team and volunteers. Our goal is to increase the participation of developers and designers in the standards development process.

Annotation service policies

This annotation experiment adheres to W3C's privacy policy. We do not use cookies or track usage, and we only require login to make an annotation.

Annotations are subject to moderation. Any annotations that are spam, trolling, abusive, or use rude language, will be edited or deleted, and the account suspended.

This is an experiment, and we do not guarantee persistence of the annotation service. While the service is running, all annotations will be stored on the Notes.WebPlatform.org server. For long-term persistence, we will also archive all annotations on the dedicated W3C email lists for that specification.

Acknowledgments

Thanks to Web Annotation WG and Open Annotation CG

The work that we're doing on web annotations is simultaneously being standardized in the Web Annotation Working Group, and is based in part on the data model work by the Open Annotation Community Group.

If you are interested in web annotations, please consider joining the Web Annotation WG.

Thanks to Hypothes.is

The web annotation software we're using for the client-side and server-side is Hypothes.is Annotator. They have been very generous with their time in making spec annotation possible.

All other annotation projects

There are many other annotation projects on the web, some of which are already participating in the standardization work in the Web Annotation WG.

One of our goals is interoperability of implementations and open sharing of annotations, so we welcome other annotation systems or services to join in this spec annotation experiment. If you are interested in participating in this project, please join the Spec Annotation Community Group.

Thanks to Mozilla's Firefox Accounts team

For secure (OAuth2+SSL) authentication across domains, we use the Firefox Accounts (FxA) software created by Mozilla.

Thanks to W3C

Thanks to the other W3C team (outside the WebPlatform project) for review and suggestions, and for letting us host this experimental interface on W3C specs!