Subject: Re: [edu-team] Draft newcomers page for comment

From: Brian E Carpenter <[email-masked]>
Date: Fri, 19 Feb 2010 09:05:52 +1300

I really haven't had that many comments on
http://www.cs.auckland.ac.nz/~brian/newcomers.html

With Anaheim approaching, I feel the need to take some Next Steps,
or drop the whole idea. So I will make an update a few days from now,
and then make some kind of a Last Call here before offering
the result to the web site maintainers.

Regards
   Brian Carpenter

On 2009-12-28 13:20, Brian E Carpenter wrote:
> Paul,
> 
> Yes, excellent point. I wonder if Alice has any such intro already,
> or if it can be built quickly from the RFC Editor tutorial. Otherwise,
> feel free to send text (or even, send HTML :-).
> 
> Regards
>    Brian Carpenter
> 
> 
> On 2009-12-28 10:55, Paul Hoffman wrote:
>> This looks like a great intro for newcomers, and definitely belongs on the IETF web page.
>>
>> One comment, though: the proposed page fails a large set of newcomers the same way that the Tao fails them. These folks are software developers, integrators, tech support folks, and so on, who are told to read an RFC and have no idea what it is or who created it. They absolutely do not want to get involved in the IETF: they have to understand a spec.
>>
>> I did a few runs at trying to restructure the Tao to handle these people early, but gave up. The Tao really is for people wanting to be (at least a bit) involved. Your newcomer's page, however, could help them understand the context in which RFCs come to being and are updated. Given that you said you might add structure to the page, I propose that this group be addressed first, in their own section. Topics these people seem to care about are:
>> - Who creates RFCs
>> - What the standards levels means <sigh>
>> - How RFCs are updated
>> - How to find RFCs on the same topic
>>
>> I'm happy to write this up if you want.
>>
>> --Paul Hoffman, Director
>> --VPN Consortium
>>
>

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 24 Feb 2010 16:56:21 +1300

OK, I have updated it:

I did *not* take Ray's suggestion to reduce verbiage. I think
people who want low verbiage are served by
http://www.ietf.org/content.html.

I added some stuff about 'where RFCs come from' but Paul
may care to rework that, and maybe it should be a separate
page (but it does kind of fit here).

Subject to comments before Anaheim, I'd like to offer this
to the Secretariat.

    Brian

---

From: Thomas Narten <[email-masked]>
Date: Wed, 24 Feb 2010 11:26:11 -0500

FWIW, I like this. It does give a nice general intro. I don't see how
shortening it would work.

To Paul's point, maybe there could be a separate section(s) with a
heading of something like:

"Info for software developers"

Followed with some tips/wisdom that would apply to what they probably
care about.

and "if you are a protocol developer", or "researcher", etc.

Thomas

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 24 Feb 2010 11:49:03 -0800

>http://www.cs.auckland.ac.nz/~brian/newcomers.html

Thanks! This is excellent.

>http://www.ietf.org/content.html.

Agree.

>page (but it does kind of fit here).

It fits here fine, and it is appropriate as an appendix. The format is fine for developers and other spec writers who need an introduction to RFCs.

One addition: errata. I propose a bullet just before "Finding RFCs is an art":
. *Some RFCs have errata.* As people read and re-read RFCs, they often find mistakes. When those people are kind enough to report those mistakes to the RFC Editor, the errata can become associated with the RFC. You can see the errata in the search results from the RFC Editor site. Most of the errata reported is editorial in nature, but sometimes the errata is a technical mistake that was not found before the RFC was published; therefore, looking at the errata for an RFC is always a good idea.

Also,  "Finding RFCs is an art" could be  "Finding RFCs for a particular topic is an art". Finding the RFC by number is trivial.

--Paul Hoffman, Director
--VPN Consortium

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 25 Feb 2010 10:03:34 +1300

Thanks Paul, I have incorporated those suggestions.

Regards
   Brian

---

From: Alice Hagens <[email-masked]>
Date: Thu, 25 Feb 2010 14:28:58 -0500

Hi Brian,

A few notes on "Where do RFCs come from?" on http://www.cs.auckland.ac.nz/~brian/newcomers.html

> Any other RFC is informational in nature, even if it reads like a technical specification and even if a marketing person asserts that it's a standard. 

Suggested:
Any other RFC is Informational, Experimental, or Historic in nature, even if it reads like a technical specification and even if a marketing person asserts that it's a standard. 

Rationale: 
Clearly you're using "informational" in a general sense here, but since it *is* a category name it's perhaps confusing. (Any other RFC is not Informational.)

> Standards track RFCs come in four flavors:
...
> Best Current Practice (BCP). This is a single stage variant for more operational specifications.   

Suggested:
Standards track RFCs come in three flavors:
...
Additionally, Best Current Practice (BCP) is an "almost standard". This is a single stage variant for more operational specifications.

Rationale: 
BCPs are not published with the Standards Track designation in the header. Bob refers to them as "almost standard" in his RFC tutorial slides (slide 23 of ftp://ftp.rfc-editor.org/in-notes/rfc-editor/tutorial.latest.pdf). 

> Most of the errata reported is editorial in nature, but sometimes the errata is a technical mistake that was not found before the RFC was published; therefore, looking at the errata for an RFC is always a good idea.

Suggested:
Errata include technical mistakes as well as editorial errors that were not found in the RFC before it was published; reviewing the errata for an RFC is always a good idea.

Rationale: 
For all errata the breakdown is about 50/50, rather than "mostly editorial", although the errata type labels (Editorial/Technical) should be taken with a grain of salt (as they are selected by the submitter and generally not corrected afterwards).

Searching from http://www.rfc-editor.org/errata.php yesterday, the breakdown looked like:

    Technical / Editorial
All       1056 / 944
--------------------
Verified   498 / 297
Reported   437 / 425
Held        79 / 172
Rejected    42 /  50

Thanks,

Alice
for the RFC Editor

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 26 Feb 2010 10:29:14 +1300

Hi Alice,

On 2010-02-26 08:28, Alice Hagens wrote:
> Hi Brian,
> 
> A few notes on "Where do RFCs come from?" on
>> Any other RFC is informational in nature, even if it reads
>> like a technical specification and even if a marketing
>> person asserts that it's a standard.
> 
> Suggested: Any other RFC is Informational, Experimental, or
> Historic in nature, even if it reads like a technical
> specification and even if a marketing person asserts that
> it's a standard.
> 
> Rationale: Clearly you're using "informational" in a general
> sense here, but since it *is* a category name it's perhaps
> confusing. (Any other RFC is not Informational.)

My rationale for not making this change: you are of course
correct, but I really want to keep this text as simple as
humanly possible. I thought about this while originally
writing it and consciously decided to elide details.
I'd be very interested to hear other opinions.

> Suggested: Standards track RFCs come in three flavors: ... 
> Additionally, Best Current Practice (BCP) is an "almost
> standard". This is a single stage variant for more
> operational specifications.
> 
> Rationale: BCPs are not published with the Standards Track
> designation in the header. Bob refers to them as "almost
> standard" in his RFC tutorial slides (slide 23 of
> ftp://ftp.rfc-editor.org/in-notes/rfc-editor/tutorial.latest.pdf).

My rationale for not making this change: same.

>> Most of the errata reported is editorial in nature, but
>> sometimes the errata is a technical mistake that was not
>> found before the RFC was published; therefore, looking at
>> the errata for an RFC is always a good idea.
> 
> Suggested: Errata include technical mistakes as well as
> editorial errors that were not found in the RFC before it was
> published; reviewing the errata for an RFC is always a good
> idea.

Agreed.

> 
> Rationale: For all errata the breakdown is about 50/50,
> rather than "mostly editorial", although the errata type
> labels (Editorial/Technical) should be taken with a grain of
> salt (as they are selected by the submitter and generally not
> corrected afterwards).

Real data is very helpful, thanks.

     Brian

> Technical / Editorial All       1056 / 944 
> -------------------- Verified   498 / 297 Reported   437 /
> 425 Held        79 / 172 Rejected    42 /  50
> 
> Thanks,
> 
> Alice for the RFC Editor
> 
>> Regards Brian