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

Abstract

   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.

Status of This Memo

   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 Notice

   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



Sheffer                 Expires December 27, 2016               [Page 1]

Internet-Draft               RFC Annotations                   June 2016


   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.

1.  Introduction

   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.

1.1.  Conventions used in this document

   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].

2.  Overview

   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.






Sheffer                 Expires December 27, 2016               [Page 2]

Internet-Draft               RFC Annotations                   June 2016


3.  Advantages

   We foresee RFC annotations being used for a variety of purposes by
   RFC consumers, including:

   -  Providing feedback on correctness and pointing out errors.  This
      is a much easier process than submitting errata, and as such would
      likely yield a larger number of corrections.

   -  Pointing out and even discussing implementation issues (annotation
      systems allow a user to "reply" to another user's comments).

   -  Linking to other standards and to implementations.

   -  Proposing ideas for and initiating discussion on "next generation"
      standards.

   Other advantages are indirect:

   -  Improving the appearance of RFCs, bringing them more in line with
      people's expectations of web documents.

   -  Bringing in more people into the standards discussion, and
      eventually into the IETF.

4.  Potential Risks

   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.

4.1.  Annotations can be improper and abusive

   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.

4.2.  IPR issues around annotations

   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.



Sheffer                 Expires December 27, 2016               [Page 3]

Internet-Draft               RFC Annotations                   June 2016


4.3.  Security and Privacy

   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.

4.4.  Long-term retention of annotations

   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.

4.5.  What if we build it and nobody comes

   This would constitute a failure of the experiment, but would not have
   any other ill effects.

5.  Proposed Technical Solution

   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.

6.  Trying it for Yourself

   -  Go to https://hypothes.is/, paste a link, e.g.
      https://tools.ietf.org/html/rfc1149 and press Annotate.




Sheffer                 Expires December 27, 2016               [Page 4]

Internet-Draft               RFC Annotations                   June 2016


   -  Now open the sidebar to view existing public annotations.

   -  Highlight some text and right-click it.  You will need to sign up
      for an account to create your own annotations.

7.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC3933]  Klensin, J. and S. Dawkins, "A Model for IETF Process
              Experiments", BCP 93, RFC 3933, DOI 10.17487/RFC3933,
              November 2004, <http://www.rfc-editor.org/info/rfc3933>.




































Sheffer                 Expires December 27, 2016               [Page 5]

Internet-Draft               RFC Annotations                   June 2016


Appendix A.  Document History

A.1.  draft-sheffer-ietf-rfc-annotations-00

   Initial version.

Author's Address

   Yaron Sheffer
   Intuit

   EMail: yaronf.ietf@gmail.com







































Sheffer                 Expires December 27, 2016               [Page 6]