| Network Working Group | Y. Sheffer |
| Internet-Draft | Intuit |
| Intended status: Informational | June 25, 2016 |
| Expires: December 27, 2016 |
Requesting Comments: Enabling Readers to Annotate RFCs
draft-sheffer-ietf-rfc-annotations-00
RFCs were initially intended as, literally, requests for comments. Since then, they have turned into standards documents, with a peculiar process to report errors and a highly onerous process to actually have the RFC modified/republished. Non-IETF participants are typically unaware of any way to provide feedback to published RFCs, other than direct email to the listed authors. This is very different from the way many web specifications are developed today and arguably leads to the value of published RFCs diminishing over time. This document proposes an experiment to remedy this situation through the deployment of web annotations.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 27, 2016.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
IETF participants use the term “RFC” on a daily basis. We all know that “RFC” stands for “Request for Comments”. However the RFCs we publish are anything but requests for comments. RFCs today are static documents that do not invite comments. Acute readers who insist on providing feedback will find the following text: “Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfcXXXX.” Once on this page, they will only find the email address of a working group, which may long be defunct.
We can do better than that. This document proposes, as a process experiment [RFC3933], to enable web annotations on published RFCs. The target audience is non-IETF participants, essentially the IETF’s customers. We discuss the advantages of such a system and the risks associated with it.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
We propose to enable, for an initial period of 1 year, annotations on published RFCs. Document readers will be able to attach textual comments to published RFCs, and these comments will be public, visible to all other readers who will also be able to respond to them.
Specifically, we recommend using the Hypothesis (https://hypothes.is/) system on our “tools” RFCs, https://tools.ietf.org/html/rfcXXXX. We propose not to build any custom infrastructure around this system but rather to use it as-is. When the experiment is done, we will publish an experiment report which will enable the IETF to decide whether this is of benefit for the long term.
We foresee RFC annotations being used for a variety of purposes by RFC consumers, including:
Other advantages are indirect:
The following section lists some of the issues and risks associated with this proposal, along with a few concrete ways to mitigate some of them.
From a legal perspective, IETF deals with user-generated content continuously (Internet drafts, mailing lists, wikis), so we know how to solve the problem.
However there can be a reputation cost, and in extreme cases people may be driven away from a document because of defacement. We might need to apply some after-the-fact moderation to annotations, similarly to what we have now on the IETF discussion list.
All public annotations made on Hypothesis are explicitly in the public domain. See also the Hypothesis Terms of Service, https://hypothes.is/terms-of-service/. Note that Hypothesis itself is a non-profit organization.
Before they can annotate any pages, users need to register into Hypothesis. Pseudonyms are explicitly allowed, but an email address must be provided. Hypothesis does not currently support any federated login such as OpenID.
The Hypothesis TOS declares that they do not track users of the service. As far as the we have seen, they only deploy a Google Analytics cookie.
Issue: can the GA cookie be disabled for particular URLs?
All traffic between the user’s browser and Hypothesis is SSL-protected.
If at the end of the experiment we choose to migrate to a different platform or to deploy a private copy of Hypothesis, we should be able to use their documented API to retrieve any extant annotations and store them into the new system.
This would constitute a failure of the experiment, but would not have any other ill effects.
Technically, to enable annotations we simply need to add one line to each RFC published on the “tools” site:
<script async defer src="https://hypothes.is/embed.js"></script>
RFC authors and WG participants can be alerted whenever their documents are annotated using RSS and Atom feeds such as: https://hypothes.is/stream.rss?uri=https://tools.ietf.org/html/rfc1149.
The Hypothesis system is open source, which means that it can be adopted to our needs during the experiment or later.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3933] | Klensin, J. and S. Dawkins, "A Model for IETF Process Experiments", BCP 93, RFC 3933, DOI 10.17487/RFC3933, November 2004. |
Initial version.