Subject: [edu-team] My notes on Editor Training

From: "Spencer Dawkins" <[email-masked]>
Date: Mon, 10 Nov 2003 20:27:12 -0600

Many of you are getting used to the situation where I say "this
document/presentation is great, and I only have a few pages of
comments"...

I attended Avri's presentation of the Editor Training. These are my
notes from that presentation. It was great, and ...

- It was a slip of the lip, but sometimes, we talked about "RFC Editor
training" - of course, we're talking about I-D editors. I wonder what
this distinction is worth, given the overlap, but that's not for this
team to worry about.

- Most of the attendees (and the room was mostly full) were document
editors. Many had edited drafts that became RFCs. I think this means
something.

- I like the section title "the RFC end game". I wonder about
inserting this idea into the training very early - as in, if you're
not planning to produce a document that will be published as an RFC,
don't start down this path.

- Avri made a distinction between "on time" and "timely". My
suggestion is to make this concrete - we had about 900 or so drafts
published in the week or two before the I-D cutoffs. These were "on
time", but were they "timely"? Would your document get more attention
if it wasn't one of the 900, published in the flood?

- Avri made a nice distinction between the WG chair "knowing what
consensus is" and the editor "saying what consensus is". I don't see
how this can be anything but iterative - ("did I get it right?", "did
I get it right?", "can you hear me now?").

- We had a question about "does a document have to be complete?". Avri
handled the question well, but some discussion of "complete enough"
would be good in the presentation. Maybe also Mike O'Dell's quote -
"it doesn't have to finish, but it does have to stop"...

- the discussion of "decision to last call" should say whose
responsibility it is to track issues (or at least that everyone needs
to know who is responsible for tracking issues in this working group).

- We had some lively discussion of ESL and choice of words. Not only
word choices matter, but also use of idioms.

- We had some lively discussion about how extensive a terminology
section should be.

- We had some lively discussion of the use of explicit requirements
language.

- Perhaps we should explicitly suggest publishing an outline early, if
the document is starting with a clean sheet of paper.

- Avri did some philosophy about what it means to "win" as an
individual author - in order to "win" having your document adopted as
a working group document, you have to "lose" control over its
contents. This whole discussion was pretty profound.

- We took a note to correct the actual title of 2119.

- I'm trying to remember if xml2rfc supports the normative/informative
reference split - does anyone know?

- It would be nice to show a good example of an abstract.

- We had a number of questions and comments about exactly what happens
with very late updates to documents (post-IESG approval). My
impression is that this is very ad hoc (RFC Editor may call editors,
wg chairs, ADs, or do something else). Someone pointed out that the
RFC Editor is now providing diffs during 48-hour review. It would be
nice to have Aaron Falk or some similar victim review this portion of
the presentation, and point out anything else that would be helpful to
include.

- We had a question about the use of 2119 language for Experimental
and Informational documents.

- We were reminded of additional security considerations for MIBs in
the MIB checklist.

- We heard a rumor of "exactly one mandatory-to-implement" as a
current IESG requirement, where there are alternatives.

- spelling - "ID-nits", "psuedo".

- If it's possible to give examples of documents with different IANA
delegation requirements, that might be useful.

- There was fairly widespread use of Latex mentioned.

- I don't think the "second last call limited to items from first last
call" statement is correct - see "correct technical objections are
always in order" in WG chairs training slides. In fact, 2026 doesn't
require (I don't think it even describes) "working group last call".

- We had a request to put these slides in the proceedings.

- We should mention the RFC Errata pages in the presentation.

Spencer

_______________________________________________
edu-team mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/edu-team

---

From: Avri Doria <[email-masked]>
Date: Tue, 11 Nov 2003 10:19:26 -0600

Thanks for the comments.

A few response/comments below.

a.

> this distinction is worth, given the overlap, but that's not for this

yes and know.  we are talking about I-Ds that are headed for RFC.  
specifically talking about editors of WG documents.  the final state is 
intended to be an RFC

> editors. Many had edited drafts that became RFCs. I think this means

we had another variety of participant i found out.  WG chairs who came 
to check it out to see if it was a class they wanted to send their 
editors too.  the ones i talked to, told me they planned to recommend 
the session to their editors.

a few new editors also came up and thanked me for gathering all these 
things in one place.

all in all, the feedback was gratifying.

> don't start down this path.

i think i need to add some content to this section.

> I get it right?", "can you hear me now?").

actually i think i should have said wg chairs - determining what the 
consensus is ...

> "it doesn't have to finish, but it does have to stop"...

i think i should add a slide on this topic.

> to know who is responsible for tracking issues in this working group).

good idea

> - We had some lively discussion about how extensive a terminology

yeah, and i sort of stumbled on this.  the suggen from some parts of 
the floor seemed to call for an extensive terminology section.

which make me wonder whether the unenviable task of creating a glossary 
of accepted TERMS and IETF definitions isn't a task that is worth being 
done.  sort of a Well Known IETF Terms RFC.

not really an EDU activity.

> - We had some lively discussion of the use of explicit requirements

I must admit this is one of my issues.  we have a disconnect between 
2119 that states the the CHOSEN WORDS only apply to Stds, and their use 
in Info and Exper.

> - We took a note to correct the actual title of 2119.

yeah, that was a remenat of my intitial sort of flippant outline and i 
just forgot to go back and fix it.  oops.

> - It would be nice to show a good example of an abstract.

hmmm. maybe, but that is risky.
i think it would be good for me to actually create a slide on the 
creaton of one as opposed to just talking to the theme.

> the presentation, and point out anything else that would be helpful to

good idea.  i felt sort of on thin ice on some of the end game stuff, 
since i am not really sure of what goes on behind the curtain.  but i 
finished the presentation too late to have it checked.  will definitely 
do so before the next run.

> - spelling - "ID-nits", "psuedo".

hey, at least it got a laugh.

> delegation requirements, that might be useful.

good idea.
i need to do more work on this section.

> - There was fairly widespread use of Latex mentioned.

how embarrassing that i forgot about it completely.
definitely lost geek points.

> require (I don't think it even describes) "working group last call".

i need to clean this part up.  don't want to get into it too deeply 
though since it is more of a wg chair issue.

> - We had a request to put these slides in the proceedings.

and where else will be be posting them?

> - We should mention the RFC Errata pages in the presentation.

yes, forgot that completely.

a.

---

From: Harald Tveit Alvestrand <[email-masked]>
Date: Tue, 11 Nov 2003 20:57:43 -0600

> reference split - does anyone know?

It does - it's an upgrade to the DTD that was done after the RFC was 
published. See release notes.