idnits 2.17.1
draft-sheffer-ietf-rfc-annotations-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack a Security Considerations section.
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document doesn't use any RFC 2119 keywords, yet seems to have RFC
2119 boilerplate text.
-- The document date (December 27, 2016) is 2670 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
No issues found here.
Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group Y. Sheffer
3 Internet-Draft Intuit
4 Intended status: Informational December 27, 2016
5 Expires: June 30, 2017
7 Requesting Comments: Enabling Readers to Annotate RFCs
8 draft-sheffer-ietf-rfc-annotations-01
10 Abstract
12 RFCs were initially intended as, literally, requests for comments.
13 Since then, they have turned into standards documents, with a
14 peculiar process to report errors and a highly onerous process to
15 actually have the RFC modified/republished. Non-IETF participants
16 are typically unaware of any way to provide feedback to published
17 RFCs, other than direct email to the listed authors. This is very
18 different from the way many web specifications are developed today
19 and arguably leads to the value of published RFCs diminishing over
20 time. This document proposes an experiment to remedy this situation
21 through the deployment of web annotations.
23 Status of This Memo
25 This Internet-Draft is submitted in full conformance with the
26 provisions of BCP 78 and BCP 79.
28 Internet-Drafts are working documents of the Internet Engineering
29 Task Force (IETF). Note that other groups may also distribute
30 working documents as Internet-Drafts. The list of current Internet-
31 Drafts is at http://datatracker.ietf.org/drafts/current/.
33 Internet-Drafts are draft documents valid for a maximum of six months
34 and may be updated, replaced, or obsoleted by other documents at any
35 time. It is inappropriate to use Internet-Drafts as reference
36 material or to cite them other than as "work in progress."
38 This Internet-Draft will expire on June 30, 2017.
40 Copyright Notice
42 Copyright (c) 2016 IETF Trust and the persons identified as the
43 document authors. All rights reserved.
45 This document is subject to BCP 78 and the IETF Trust's Legal
46 Provisions Relating to IETF Documents
47 (http://trustee.ietf.org/license-info) in effect on the date of
48 publication of this document. Please review these documents
49 carefully, as they describe your rights and restrictions with respect
50 to this document. Code Components extracted from this document must
51 include Simplified BSD License text as described in Section 4.e of
52 the Trust Legal Provisions and are provided without warranty as
53 described in the Simplified BSD License.
55 1. Introduction
57 IETF participants use the term "RFC" on a daily basis. We all know
58 that "RFC" stands for "Request for Comments". However the RFCs we
59 publish are anything but requests for comments. RFCs today are
60 static documents that do not invite comments. Acute readers who
61 insist on providing feedback will find the following text:
62 "Information about the current status of this document, any errata,
63 and how to provide feedback on it may be obtained at http://www.rfc-
64 editor.org/info/rfcXXXX." Once on this page, they will only find the
65 email address of a working group, which may long be defunct.
67 We can do better than that. This document proposes, as a process
68 experiment [RFC3933], to enable web annotations on published RFCs.
69 The target audience is non-IETF participants, essentially the IETF's
70 customers. We discuss the advantages of such a system and the risks
71 associated with it.
73 1.1. Conventions used in this document
75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
77 document are to be interpreted as described in [RFC2119].
79 2. Overview
81 We propose to enable, for an initial period of 1 year, annotations on
82 published RFCs. Document readers will be able to attach textual
83 comments to published RFCs, and these comments will be public,
84 visible to all other readers who will also be able to respond to
85 them.
87 Specifically, we recommend using the Hypothesis
88 (https://hypothes.is/) system on our "tools" RFCs,
89 https://tools.ietf.org/html/rfcXXXX. We propose not to build any
90 custom infrastructure around this system but rather to use it as-is.
91 When the experiment is done, we will publish an experiment report
92 which will enable the IETF to decide whether this is of benefit for
93 the long term.
95 3. Advantages
97 We foresee RFC annotations being used for a variety of purposes by
98 RFC consumers, including:
100 - Providing feedback on correctness and pointing out errors. This
101 is a much easier process than submitting errata, and as such would
102 likely yield a larger number of corrections.
104 - Pointing out and even discussing implementation issues (annotation
105 systems allow a user to "reply" to another user's comments).
107 - Linking to other standards and to implementations.
109 - Proposing ideas for and initiating discussion on "next generation"
110 standards.
112 Other advantages are indirect:
114 - Improving the appearance of RFCs, bringing them more in line with
115 people's expectations of web documents.
117 - Bringing in more people into the standards discussion, and
118 eventually into the IETF.
120 4. Potential Risks
122 The following section lists some of the issues and risks associated
123 with this proposal, along with a few concrete ways to mitigate some
124 of them.
126 4.1. Annotations can be improper and abusive
128 From a legal perspective, IETF deals with user-generated content
129 continuously (Internet drafts, mailing lists, wikis), so we know how
130 to solve the problem.
132 However there can be a reputation cost, and in extreme cases people
133 may be driven away from a document because of defacement. We might
134 need to apply some after-the-fact moderation to annotations,
135 similarly to what we have now on the IETF discussion list.
137 4.2. IPR issues around annotations
139 All public annotations made on Hypothesis are licensed under the
140 Creative Commons CC0 license, which puts them explicitly in the
141 public domain.
143 See also the Hypothesis Terms of Service, https://hypothes.is/terms-
144 of-service/. Note that Hypothesis itself is a non-profit
145 organization.
147 4.3. Security and Privacy
149 Before they can annotate any pages, users need to register into
150 Hypothesis. Pseudonyms are explicitly allowed, but an email address
151 must be provided. Hypothesis does not currently support any
152 federated login such as OpenID.
154 The Hypothesis TOS declares that they do not track users of the
155 service. As far as the we have seen, they only deploy a Google
156 Analytics cookie.
158 Issue: can the GA cookie be disabled for particular URLs?
160 All traffic between the user's browser and Hypothesis is SSL-
161 protected.
163 4.4. Spam
165 So far spam has not been a problem with Hypothesis annotations,
166 because users need to demonstrate a valid email address. If it ever
167 becomes a problem, a process can be worked out where IETF volunteers
168 monitor new annotations for spam, and the Hypothesis team removes it
169 within a reasonable time.
171 4.5. Long-term retention of annotations
173 If at the end of the experiment we choose to migrate to a different
174 platform or to deploy a private copy of Hypothesis, we will be able
175 to use their documented API to retrieve any extant annotations and
176 store them into the new system.
178 4.6. What if we build it and nobody comes
180 This would constitute a failure of the experiment, but would not have
181 any other ill effects.
183 5. Proposed Technical Solution
185 Technically, to enable annotations we simply need to add one line to
186 each RFC published on the "tools" site:
188 " "
189 A bit of additional code would be needed to display the IETF Note
190 Well text if we choose to inform users that they implicitly agree to
191 it.
193 RFC authors and WG participants can be alerted whenever their
194 documents are annotated using RSS and Atom feeds such as:
195 https://hypothes.is/stream.rss?uri=https://tools.ietf.org/html/
196 rfc1149.
198 The Hypothesis system is open source, which means that it can be
199 adopted to our needs during the experiment or later.
201 6. Trying it for Yourself
203 - Go to https://hypothes.is/, paste a link, e.g.
204 https://tools.ietf.org/html/rfc1149 and press Annotate.
206 - Now open the sidebar to view existing public annotations.
208 - Highlight some text and right-click it. You will need to sign up
209 for an account to create your own annotations.
211 7. Normative References
213 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
214 Requirement Levels", BCP 14, RFC 2119,
215 DOI 10.17487/RFC2119, March 1997,
216 .
218 [RFC3933] Klensin, J. and S. Dawkins, "A Model for IETF Process
219 Experiments", BCP 93, RFC 3933, DOI 10.17487/RFC3933,
220 November 2004, .
222 Appendix A. Document History
224 A.1. -01
226 - Minor changes after meeting with the Hypothesis team.
228 A.2. draft-sheffer-ietf-rfc-annotations-00
230 Initial version.
232 Author's Address
234 Yaron Sheffer
235 Intuit
237 EMail: yaronf.ietf@gmail.com