Subject: [edu-team] Slides for "What Makes Good RFC?" tutorial

From: Mirjam Kuehne <[email-masked]>
Date: Wed, 14 Mar 2018 11:15:10 +0100

Hi all,

Please find attached the slides for the "What Makes Good RFC/ID" tutorial.

Please take a look and send any feedback back to Adrian and Spencer.

Kind regards,
Mirjam

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 14 Mar 2018 13:48:59 +0000

I will read more carefully and provide more feedback later (hopefully in time for this upcoming IETF), but early on it says
	The WG "owns" the document

The quotes should be removed and the word should instead be *bold*  You're turning over copyright control, and if you have proprietary things you want to keep control of, then maybe the IETF isn't the place to use.

On 3/14/18, 6:17 AM, "Mirjam Kuehne" <[email-masked]> wrote:

    Hi all,

    
    Kind regards,
    Mirjam

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 14 Mar 2018 14:17:37 +0000

Adrian,

On Wed, Mar 14, 2018, 08:49 Salz, Rich <[email-masked]> wrote:

> I will read more carefully and provide more feedback later (hopefully in
> time for this upcoming IETF), but early on it says
> The quotes should be removed and the word should instead be *bold*  You're
> turning over copyright control, and if you have proprietary things you want
> to keep control of, then maybe the IETF isn't the place to use.
>

This is screaming for a slide on draft IPR options, isn't it?

That would capture Rich's accurate observation, too, I think.

Spencer

---

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 14 Mar 2018 18:13:50 -0000

We can do that, but I think this is wandering off the brief quite significantly (noting that we already wandered some way).
 
We are not there to discuss the details of the RFC process (about which Rich is right but actually doesn't go far enough - the ownership he mentions comes at the time of posting the first draft). The point of the bullet (on slide 4) is to allow the presenter a chance to observe that the authors' idea may get significantly changed by the discussions in the WG and that the final product might even be something the original authors are not happy with. Also the usual subtext about WG chairs appointing editors.
 
But can one slide on IPR hurt? Probably not.
 
A
 
From: Spencer Dawkins at IETF [mailto:[email-masked]] 
Sent: 14 March 2018 14:18
To: Salz, Rich
Cc: Mirjam Kuehne; EDU Team; Adrian Farrel
Subject: Re: [edu-team] Slides for "What Makes Good RFC?" tutorial
 
Adrian,

 
 
Spencer

    Hi all,

    Kind regards,
    Mirjam

---

From: Alice Russo <[email-masked]>
Date: Wed, 14 Mar 2018 13:57:37 -0700

Adrian, Spencer,

Thanks for your work on this tutorial. As you can imagine, I find this topic important. :) Suggestions below; I won't be offended if they're not incorporated!

Alice
--

s6
add clear statement that using a tool to write your I-D will help (esp. with boilerplate and references) and perhaps a pointer to resources.

Perhaps add it here:
• You might as well include it from day 1
• Tools make it easier (https://www.rfc-editor.org/pubprocess/tools/)

Or here:
• Get it for free with XML2RFC 
(or various tools for creating I-Ds: https://www.rfc-editor.org/pubprocess/tools/)

--
s12
insert "and ask questions" [rationale: It's a fair warning to the authors; however, in general, the RFC Editor sends questions of authors in hopes of avoiding changes to technical meaning. Mentioning the questions helps manage expectations re: you will likely receive questions *and* every effort is made not to harm technical meaning (and to flag changes that might do so) *but* you still should take time to try to write clearly.)

OLD
The RFC Editor will fix things, but...
– The RFC Editor can only guess at your real meaning 
– Every change risks introducing a technical error
  • Authors assume changes are just a fix in English and didn’t spot the change in meaning

NEW
The RFC Editor will fix things and ask questions, but...
– The RFC Editor can only guess at your real meaning
– Every change risks introducing a technical error
...

OR
The RFC Editor will fix things, but...
– The RFC Editor can only guess at your real meaning and ask questions
– Every change risks introducing a technical error
...

s12 again
OLD
– RFC Editor workshops on I-D writing
 • https://www.ietf.org/edu/documents/tutorial76.pdf
 • http://trac.tools.ietf.org/group/iesg/trac/wiki/DocumentLanguageEditing
 
NEW
RFC Editor resources for writing I-Ds
 • https://www.rfc-editor.org/pubprocess/tools/
 • https://www.rfc-editor.org/styleguide/tips/

[rationale: 1st one was 404. 2nd one (DocumentLanguageEditing page) was info from IETF 89 for specific drafts used in that workshop. 
- https://www.rfc-editor.org/pubprocess/tools/: List of tools for creating I-Ds if it wasn't added to slide 6
- https://www.rfc-editor.org/styleguide/tips/ has some writing resources. It overlaps in concept w/ s15 (under 'writing style').
Alternatively: could do https://www.rfc-editor.org/materials/tools_ids_rfcs_94.pdf
(tutorial slides from IETF 94 primarily about xml2rfc and NroffEdit.)]

s13
New rules will allows -> New rules will allow
73 -> 72

This slide seems the opportunity to mention the Brave New World Coming Soon
-- perhaps simply a pointer to the RFC Format FAQ under Resources?
"A glimpse of the future: https://www.rfc-editor.org/rse/format-faq/"

s21 and s22 
There is some overlap with the text on these slides; is it intentional?

s23
Personal Identifying Information -> Personally Identifiable Information
[rationale: typically PII seems the latter]

s25
 • IRTF RFCs aren’t Standards Track – Experimental or Informational
 • IRTF RFCs aren’t Standards Track – they are Experimental or Informational

[could be misread]

s27
Independent Stream Editor (ISE) -> Independent Submissions Editor (ISE)

[Adrian, your title, your choice ;)  Clearly, it's appeared in different forms in different places over time. The latter seems rather common.]

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 14 Mar 2018 18:09:07 -0500

Hi, Adrian,

On Wed, Mar 14, 2018 at 1:13 PM, Adrian Farrel <[email-masked]> wrote:

> We can do that, but I think this is wandering off the brief quite
> significantly (noting that we already wandered some way).
>
>
>
> We are not there to discuss the details of the RFC process (about which
> Rich is right but actually doesn't go far enough - the ownership he
> mentions comes at the time of posting the first draft). The point of the
> bullet (on slide 4) is to allow the presenter a chance to observe that the
> authors' idea may get significantly changed by the discussions in the WG
> and that the final product might even be something the original authors are
> not happy with. Also the usual subtext about WG chairs appointing editors.
>
>
>

I know you'll do the right thing ;-)

Spencer

>
>
> A
>
>
>
> *From:* Spencer Dawkins at IETF [mailto:[email-masked]]
> *Sent:* 14 March 2018 14:18
> *To:* Salz, Rich
> *Cc:* Mirjam Kuehne; EDU Team; Adrian Farrel
> *Subject:* Re: [edu-team] Slides for "What Makes Good RFC?" tutorial
>
>
>
> Adrian,
>

---

From: "Adrian Farrel" <[email-masked]>
Date: Thu, 15 Mar 2018 08:15:53 -0000

Hi Alice, 

Thanks for caring.

> s6
> add clear statement that using a tool to write your I-D will help (esp. with
> boilerplate and references) and perhaps a pointer to resources.
> 
> Perhaps add it here:

Yes

> s12
> insert "and ask questions"
 
> – Every change risks introducing a technical error

Yes

> rationale: 1st one was 404.

Hmmm. Website re-org again :-(
And https://www.ietf.org/proceedings/76/RFCEd.html is missing the slides.
https://www6.ietf.org/edu/ exists, but www.ietf.org/edu is a redirect to https://datatracker.ietf.org/group/emodir/about/
And https://www6.ietf.org/edu/documents/tutorial76.pdf works fine
I still don't understand why this all happened :-)
I raised a ticket.

> 2nd one (DocumentLanguageEditing page) was info
> from IETF 89 for specific drafts used in that workshop.

OK, I specifically wanted the tutorial material rather than just the tools.
The tips are good, though, so I'll add that reference

> New rules will allows -> New rules will allow

Thanks

> "A glimpse of the future: https://www.rfc-editor.org/rse/format-faq/"

Yes

> There is some overlap with the text on these slides; is it intentional?

Hah, yes. Found and fixed. probably Spencer was bug-seeding

> [rationale: typically PII seems the latter]

Nice

>  • IRTF RFCs aren’t Standards Track – they are Experimental or Informational

OK

> [Adrian, your title, your choice ;)  Clearly, it's appeared in different forms in
> different places over time. The latter seems rather common.]=

<red face>

Thanks!
Adrian