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 email@example.com 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.
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.
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.
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.
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.
Click “Forgot password?” on the sign-in dialog and enter the email address you signed up for your account with.
Enter the email address you signed up for your account with.
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.
To create an annotation select the text you want and click on the pen icon.
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
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.
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 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:
To edit an annotation, simply hover over the annotation card and select the edit button.
To reply to an annotation, hover over the annotation card and select reply.
To delete an annotation, hover over the corresponding annotation card and select 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.
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.
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.
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.
To turn highlighting mode off, simply select it again from the controlbar menu.
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.
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.
Click on the up marker and down marker to navigate to the previous and next annotations on the page.
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”.
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.
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.
When leaving feedback on a specification, you should follow these basic guidelines:
Feel free to post questions, comments, or suggestions on the firstname.lastname@example.org mailing list.
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.
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.
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.
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.
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.
For secure (OAuth2+SSL) authentication across domains, we use the Firefox Accounts (FxA) software created by Mozilla.
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!