Subject: Re: Wikis for RFCs

From: Yaron Sheffer <[email-masked]>
Date: Fri, 16 Sep 2011 21:53:54 +0300

Hi Paul,

I strongly support the idea of wikis interlinked with RFCs. I'd like to offer two very successful examples, both much more relevant than Wikipedia: the PHP Manual (see for examplehttp://www.php.net/manual/en/function.date-parse.php), and the jQuery manual (e.g.http://api.jquery.com/bind/). In both cases these are managed as extended comments to the main text. I believe RFCs will need a more sophisticated solution, since they are obviously much larger than a manual page.

Thanks,
	Yaron

Date: Fri, 16 Sep 2011 10:06:21 -0700
From: Paul Hoffman<[email-masked]>
To: IETF Discussion<[email-masked]>
Subject: Wikis for RFCs
Message-ID:<[email-masked]>
Content-Type: text/plain; charset=us-ascii

On Sep 16, 2011, at 9:39 AM, Keith Moore wrote:

> On Sep 16, 2011, at 10:52 AM, Cyrus Daboo wrote:
>
>> Again I would like to bring up the idea of every RFC having an associated wiki page(s). The goal here is to provide a way for implementors to add comments, annotations, clarifications, corrections etc to augment the RFCs. Whilst such commentary can often be found on IETF mailing lists after an RFC is published locating those and searching them can be tedious - plus the full history of discussion on various points is often not relevant to an implementor - all they need to know is what is the correct way to do it now.
>>
>> Doing something like this would obviously require some investment in additional infrastructure. There are also questions about how we would maintain the integrity of the information on the wiki pages, but I think those are things we can easily address.
> This is something that could be implemented on a volunteer basis as an experiment.  If it worked, perhaps IETF could be convinced to take it over.
Volunteer moderating of such a Wiki could easily lead to the wiki being of little or no value, and being an embarrassment to the IETF. Consider an RFC that might be construed as supporting the use of NATs on the Internet. Open commenting on the RFC could be fodder for certain people commenting about the applicability of the RFC because NATs Are Evil. There would then likely be counter-comments from people who feel that NATs Have Value. Such comments, if moderated, could be very valuable to an implementer who knows about the RFC but not the bigger picture; unmoderated comments would be no more useful than some of the permathreads on the WG list that created the RFC.

Wikipedia is about the only example of working volunteer moderation, and even then, there are cabals that supported by the paid management. Few, if any, of the unmanaged wiki sites have long-lasting value.

--Paul Hoffman

---

From: hector <[email-masked]>
Date: Fri, 16 Sep 2011 15:07:45 -0400

I don't see these ass "Wikis" but basically "blog style" flat display 
of user comments, which I often do find useful, especially for the 
user ("this way") upon user ("not always") follow ups.

A Wiki is more where you can change the main content and perhaps even 
the context.  I don't think that is a good idea for RFCs.

Yaron Sheffer wrote:
> Hi Paul,
> 
> I strongly support the idea of wikis interlinked with RFCs. I'd like to 
> offer two very successful examples, both much more relevant than 
> Wikipedia: the PHP Manual (see for 
> examplehttp://www.php.net/manual/en/function.date-parse.php), and the 
> jQuery manual (e.g.http://api.jquery.com/bind/). In both cases these are 
> managed as extended comments to the main text. I believe RFCs will need 
> a more sophisticated solution, since they are obviously much larger than 
> a manual page.
> 
> Thanks,
>     Yaron
> 
>>> Again I would like to bring up the idea of every RFC having an 
>>> associated wiki page(s). The goal here is to provide a way for 
>>> implementors to add comments, annotations, clarifications, 
>>> corrections etc to augment the RFCs. Whilst such commentary can often 
>>> be found on IETF mailing lists after an RFC is published locating 
>>> those and searching them can be tedious - plus the full history of 
>>> discussion on various points is often not relevant to an implementor 
>>> - all they need to know is what is the correct way to do it now.
>>>
>>> Doing something like this would obviously require some investment in 
>>> additional infrastructure. There are also questions about how we 
>>> would maintain the integrity of the information on the wiki pages, 
>>> but I think those are things we can easily address.
>> This is something that could be implemented on a volunteer basis as an 
>> experiment.  If it worked, perhaps IETF could be convinced to take it 
>> over.
> Volunteer moderating of such a Wiki could easily lead to the wiki being 
> of little or no value, and being an embarrassment to the IETF. Consider 
> an RFC that might be construed as supporting the use of NATs on the 
> Internet. Open commenting on the RFC could be fodder for certain people 
> commenting about the applicability of the RFC because NATs Are Evil. 
> There would then likely be counter-comments from people who feel that 
> NATs Have Value. Such comments, if moderated, could be very valuable to 
> an implementer who knows about the RFC but not the bigger picture; 
> unmoderated comments would be no more useful than some of the 
> permathreads on the WG list that created the RFC.
> 
> Wikipedia is about the only example of working volunteer moderation, and 
> even then, there are cabals that supported by the paid management. Few, 
> if any, of the unmanaged wiki sites have long-lasting value.
> 
> --Paul Hoffman
> 
> 
> _______________________________________________
> Ietf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf

---

From: Keith Moore <[email-masked]>
Date: Fri, 16 Sep 2011 15:22:08 -0400

On Sep 16, 2011, at 3:07 PM, hector wrote:

> I don't see these ass "Wikis" but basically "blog style" flat display of user comments, which I often do find useful, especially for the user ("this way") upon user ("not always") follow ups.
> 
> A Wiki is more where you can change the main content and perhaps even the context.  I don't think that is a good idea for RFCs.

I'm thinking in terms of a hybrid Wiki where the RFC content is static but the discussion is maintainable as a Wiki and can be visually associated with the RFC content.  You'd also want the RFC content to be clearly distinguished from the discussion.

Keith

---

From: Andrew Feren <[email-masked]>
Date: Fri, 16 Sep 2011 15:26:47 -0400

> I'm thinking in terms of a hybrid Wiki where the RFC content is static but the discussion is maintainable as a Wiki and can be visually associated with the RFC content.  You'd also want the RFC con…

Something like the annotate POD feature for perl modules on CPAN?

Example:
Unannotated
http://search.cpan.org/~timb/DBI-1.616/DBI.pm

Annotated
http://www.annocpan.org/~TIMB/DBI-1.616/DBI.pm

-Andrew

---

From: Keith Moore <[email-masked]>
Date: Fri, 16 Sep 2011 15:29:20 -0400

> http://www.annocpan.org/~TIMB/DBI-1.616/DBI.pm

Yes, something like that.

Keith

---

From: hector <[email-masked]>
Date: Fri, 16 Sep 2011 15:58:04 -0400

My view since we do these user collaboration, "group ware" online 
hosting software for a Living.... and deal with this "evolutionary" 
ideas that always seem to be better but not always applicable.

Realistically, it has to be single source and as a migration, I think 
it should be explored where the IETF links to the I-D have a user 
followup/comment systems ala the PHP example (but there are many 
others).  For sure the I-D.  For RFC, the "Request For Comment" still 
apply but not sure "How Much" more you want - some difference I think.

The only main issue is the decision of "membership" vs "anonymous" 
input.  That is always the main issue with any sort of group ware 
concept.  The Author should be some responsibility (e.g. the Moderator 
of the input).

The IETF can just supply the tool, the backend software for this.

--

---

From: Hector <[email-masked]>
Date: Fri, 16 Sep 2011 16:40:22 -0400

Keith,

I think we already have the basis for this with the "tools" already 
there when viewing an I-D, RFC via the tools.ietf.org url.

For example, in the last I-D submission I got, the email message did 
not have this link (but it should):

   http://tools.ietf.org/html/draft-lodderstedt-oauth-revocation-03

and it has all the top menu items, including NITS.

A relatively small plug and play "experimental" software change would 
add "USER COMMENTS" and it will be displayed at the bottom.   This 
would be the simply migration change to start this - we call it for 
our own File Library system "Follow up Comments" but its the same 
model for a message follow up concept - the toughest part is the 
ergonomics, so the suggestion is to first do it as a flat "blog" like 
display just to get the framework.

Someone can explore this today as an independent wrapper on some other 
site using the official tools.ietf.org url.  Then the IETF can decide 
to implement it as an experiment.  I would personally suggest to do it 
with I-D first.

A few great benefits I see:

   - user interest,
   - faster corrections for author to consolidate,
   - measure it for an official WG proposal,
   - wider, single source input (although the WG would
     eventually accomplish this too).

etc.

I see a lot of synergism developing here if its taking serious and 
explored first with maybe I-D first using a simply user follow-up concept.

Again, the only real battle if this is a membership concept for the 
IETF - I think it should be.  Simple:

    Email Address:
    Password:
    Display name:
    Real Name: [optional]

Use CAPTCHA input to hope avoid automated blasting.

I have no problem if Anonymous input is decided to be allowed.  Maybe 
that could be the author decision. The author should have ultimate 
control to deleted abusive input and when the follow up periods are over.

--
Hector Santos, CTO
http://www.santronics.com

hector wrote:
> Realistically, it has to be single source and as a migration, I think it 
> should be explored where the IETF links to the I-D have a user 
>>>>> I don't see these ass "Wikis" but basically "blog style" flat 
>>>>> display of user comments, which I often do find useful, especially 
>>>>> for the user ("this way") upon user ("not always") follow ups.
>>>>>
>>>>> A Wiki is more where you can change the main content and perhaps 
>>>>> even the context.  I don't think that is a good idea for RFCs.
>>>> I'm thinking in terms of a hybrid Wiki where the RFC content is 
>>>> static but the discussion is maintainable as a Wiki and can be 
>>>> visually associated with the RFC content.  You'd also want the RFC 
>>>> content to be clearly distinguished from the discussion.
>>>>
>>>> Keith

---

From: Joel jaeggli <[email-masked]>
Date: Sat, 17 Sep 2011 10:18:20 -0700

> content to be clearly distinguished from the discussion.

One of the assumptions here is that discussion without editorial
discretion can add color to static informaion. While the case for that
can certainly be made, we have abundant evidence of it not doing so in
the context of ietf mailing lists.

RFC's (WG documents in general) are the editorial filter through which
we pass/preserve the contributed discussion that is deemed informative.

> Keith
> 
> _______________________________________________ Ietf mailing list 
> [email-masked] https://www.ietf.org/mailman/listinfo/ietf
>

---

From: Keith Moore <[email-masked]>
Date: Sat, 17 Sep 2011 13:29:11 -0400

> the context of ietf mailing lists.

we have abundant evidence of there being color added in the context of ietf mailing lists.  problem is, there's a lot more than color added there.

a wiki is a different medium than email.   because people can alter and even delete contributions by others, there's some tendency to try to compromise in order to minimize change wars.   admittedly, it's an imperfect tendency.

> we pass/preserve the contributed discussion that is deemed informative.

this is not true of WG documents in general, which are often quite biased and occasionally one-sided.

as for RFCs, there's a lot of overhead associated with them, which is part of why IETF has a difficult time keeping its documents current.

Keith

---

From: Marshall Eubanks <[email-masked]>
Date: Sat, 17 Sep 2011 15:38:28 -0400

On Sat, Sep 17, 2011 at 1:29 PM, Keith Moore <[email-masked]>wrote:

> we have abundant evidence of there being color added in the context of ietf
> mailing lists.  problem is, there's a lot more than color added there.
>
> a wiki is a different medium than email.   because people can alter and
> even delete contributions by others, there's some tendency to try to
> compromise in order to minimize change wars.   admittedly, it's an imperfect
> tendency.
>
>
Instead of having a wiki, why not have a wikipedia article for each RFC ?
Whatever problems we would have with change control,
wikipedia is already dealing with.

Regards
Marshall

> as for RFCs, there's a lot of overhead associated with them, which is part
> of why IETF has a difficult time keeping its documents current.
>
> Keith
>

---

From: Keith Moore <[email-masked]>
Date: Sat, 17 Sep 2011 16:16:31 -0400

On Sep 17, 2011, at 3:38 PM, Marshall Eubanks wrote:

> Instead of having a wiki, why not have a wikipedia article for each RFC ? Whatever problems we would have with change control,

wikipedia has different goals.  they're really trying to be an encyclopedia; we're talking about using a wiki as a medium to discuss RFCs and implementation of RFCs.

Keith

---

From: Joel jaeggli <[email-masked]>
Date: Sat, 17 Sep 2011 13:28:15 -0700

On 9/17/11 10:29 , Keith Moore wrote:
>>>> display of user comments, which I often do find useful,
>>>> especially for the user ("this way") upon user ("not always")
>>>> follow ups.
>>>> 
>>>> A Wiki is more where you can change the main content and
>>>> perhaps even the context.  I don't think that is a good idea
>>>> for RFCs.
>>> 
>>> visually associated with the RFC content.  You'd also want the
>>> RFC content to be clearly distinguished from the discussion.
>> 
>> discretion can add color to static informaion. While the case for
>> that can certainly be made, we have abundant evidence of it not
>> doing so in the context of ietf mailing lists.
> 
> we have abundant evidence of there being color added in the context
> of ietf mailing lists.  problem is, there's a lot more than color
> added there.
> 
> a wiki is a different medium than email.   because people can alter
> and even delete contributions by others, there's some tendency to try
> to compromise in order to minimize change wars.   admittedly, it's an
> imperfect tendency.

the frequency with which an opinion is stated by a small but prolific
number of individuals should not confer legitimacy over less frequent
contributors.

>> RFC's (WG documents in general) are the editorial filter through
>> which we pass/preserve the contributed discussion that is deemed
>> informative.
> 
> 

I did not say that they were unbiased, I said that they served as filter
on the output.

> as for RFCs, there's a lot of overhead associated with them, which is
> part of why IETF has a difficult time keeping its documents current.
> 
> Keith
> 
>

---

From: Keith Moore <[email-masked]>
Date: Sat, 17 Sep 2011 17:17:01 -0400

> number of individuals should not confer legitimacy over less frequent

I agree.  But what does that have to do with the current discussion?

> I did not say that they were unbiased, I said that they served as filter

Indeed they do.  Which argues for having another mechanism for community input.  

Keith

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Sun, 18 Sep 2011 23:22:44 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of Joel jaeggli
> Sent: Saturday, September 17, 2011 10:18 AM
> To: Keith Moore
> Cc: hector; [email-masked]
> Subject: Re: Wikis for RFCs
> 

I think I agree that a wiki page for every RFC is too chaotic an idea to be workable.  The lists are noisy enough already.

It seems to me that if we want the capability to write down and then publish some observations about protocol implementation including problems with the specs or operational considerations, the implementation reports space is perfect for this.  They're already required when things advance from PS to DS, but there's nothing I've seen that says particularly useful information can't be written up and recorded through the same means.  If and when the advancement day comes for that protocol, the information can then be put to good use.

The only question is whether or not they can be updated once published.  I suppose we'd need a mechanism for that.  Currently that's the IESG, and I imagine that's not something that should stand for very long.  Maybe we could use Expert Review to create or update them, except in cases where the implementation report is part of a standards track advancement effort in which case it has to be the IESG.

Failing that: Have we already thrown out the idea of an Informational or BCP publication when there's sufficient collected wisdom about a protocol to write down some observations?  I think I'd rather read something that has a chance of having garnered consensus and review rather than something that's potentially tainted by the last person to click "Submit" on a wiki page.

-MSK

---

From: "Spencer Dawkins" <[email-masked]>
Date: Mon, 19 Sep 2011 10:54:09 -0500

Murry,

> I think I agree that a wiki page for every RFC is too chaotic an idea to 
> be workable.

I agree with the thought that the suggestion under consideration could 
usefully be amended as "a wiki page for every RFC that needs one".

If I write a specification, it's published as an RFC, and we don't need to 
say much else, we don't need a wiki page for that.

I'd like to suggest an amendment as "a wiki page for every protocol that 
needs one".

One of our problems is that we haven't come up with a useful way of grouping 
specifications that, taken together, describe a protocol, at some specific 
point in time. STDs should have been that grouping, but the failure for so 
many standards-track specifications to advance to full Standard made STDs 
much less relevant in the IETF as we have it today.

When we've done summary documents for protocols that have been massively 
extended over one or more decades (I'm most familiar with TCP - RFC 4614 - 
and SIP - RFC 5411), I think those have been very useful, but they tend to 
be published once - they aren't living descriptions of the protocol as it 
evolves.

Perhaps we should be thinking about how we maintain our body of corporate 
knowledge at the protocol level, which is not necessarily the individual RFC 
level.

Spencer