Re: New document shepherd writeup

[Mark Nottingham <[e-mail]>]

Hi Alvaro,

Thanks for the answers. I'm not so much asking for me (I've done this before), as I am for the new chairs we're trying to get up to speed, and the people we're trying to recruit to be document shepherds (which is one way to find future chairs). So it'd be great if these answers were reflected in the document (or links from it). I'm happy to make specific suggestions.

The IETF has a habit of expecting people to just know things, rather than writing them down. If we make the extra effort to write things down well, the organisation becomes just a bit more open, welcoming, and less opaque.

Cheers,


> On 5 May 2022, at 10:10 pm, Alvaro Retana <[e-mail]> wrote:
> 
> On May 3, 2022 at 7:18:39 PM, Mark Nottingham wrote:
> 
> 
> Mark:
> 
> Hi!
> 
> Some answers inline.  Some of the questions in the updated writeup are
> variations of questions in the previous version -- in some cases we wanted to
> be more explicit or highlight the fact that there were multiple questions in a
> specific point.
> 
> 
>> Coincidentally, I'm just writing up a document, so here are some notes on the
>> new template:
>> 
>> * Question 5 - How does the shepherd know if external review is required? Is
>> it at their discretion, or if the charter mentions it, or...?
> 
> Yes.  Any of the above.
> 
> The update
> 
>    5. Does this document need review from other IETF working groups or
>    external organizations? Have those reviews occurred?
> 
> ...is a variation of the previous
> 
>    (5) Do portions of the document need review from a particular or
>    from broader perspective, e.g., security, operational complexity,
>    AAA, DNS, DHCP, XML, or internationalization? If so, describe the
>    review that took place.
> 
> Instead of listing specific aspects we decided to generalize.
> 
> 
> 
> ...
>> * Question 11 - It would be very helpful if there were a link to a clear
>> guide for making this decision.
> 
> :-)  I'm smiling because this is probably the most incomplete-answered question
> from the previous template.  We usually get a one word answer...
> 
> Previous:
> 
>    (1) What type of RFC is being requested (BCP, Proposed Standard,
>    Internet Standard, Informational, Experimental, or Historic)? Why
>    is this the proper type of RFC? Is this type of RFC indicated in
>    the title page header?
> 
> Current:
> 
>    11. What type of RFC publication is being requested on the IETF stream
>    (Best Current Practice, Proposed Standard, Internet Standard,
>    Informational, Experimental, or Historic)? Why is this the proper
>    type of RFC? Do all Datatracker state attributes correctly reflect
>    this intent?
> 
> There are 3 questions:
> 
> (1) What type of RFC?  This information comes from the header of the document.
>     Note that "Standards Track" on the header may translate to Proposed
>     Standard or Internet Standard.
> 
> (2) Is this the right type?  Here we expect the Shepherd to provide a short
>     explanation of why the document is expected to be a BCP, PS, etc.  A
>     sentence or two should be enough.  For example, "This document should be a
>     Proposed Standard because it defines a new extension to BGP.", or
>     "Informational is the right status because it describes how ABC is used in
>     mobile networks."
> 
> (3) Does the Datatracker contain the right status indication?  Sometimes
>     documents indicate the intent to be on the Standards Track, but the
>     Datatracker indicates the status as Experimental, for example.
> 
> 
> 
> ...
>> * Question 13 - Do we need to positively confirm this with each author? If
>> so, that seems a bit absurd in some circumstances, e.g., when the author has
>> clearly been involved from day one. If not, I'd suggest rewording to remove
>> that implication.
> 
> Not all authors are as active as others.
> 
> In fact, there have been reports of people who were listed as authors (or
> Contributors) without their knowledge or explicit consent -- in some cases this
> situation has caused issues downstream.  The IESG put out a statement about it:
> 
> https://www.ietf.org/about/groups/iesg/statements/internet-draft-authorship/
> 
> 
> This question is new:
> 
>    13. Has each Author or Contributor confirmed their willingness
>    to be listed as such? If the number of Authors/Editors on the
>    front page is greater than 5, please provide a justification.
> 
> 
> I was about to send a note to the list about it -- here it is (I'll send it
> again later to make sure people not following this thread also see it):
> 
> =====
>    Dear WG Chairs:
> 
>    In line with the IESG Statement on Internet Draft Authorship [1], we ask
>    that all WG Chairs confirm the willingness of Authors and Contributors to
>    be listed as such.
> 
>    This confirmation should be done during WG adoption and WG Last Call.  At
>    the same time, we encourage the WG Chairs to question the presence of more
>    than 5 Authors/Editors on the front page whenever they notice it. Please
>    see [2] for more information.
> 
>    The recently updated Shepherd write-up [3] also includes a new related
>    entry:
> 
>       (13) Has each Author or Contributor confirmed their
>       willingness to be listed as such? If the number of
>       Authors/Editors on the front page is greater than 5,
>       please provide a justification.
> 
>    Thank you!
> 
>    Alvaro. (for the IESG)
> 
>    [1] https://www.ietf.org/about/groups/iesg/statements/internet-draft-authorship/
>    [2] https://datatracker.ietf.org/doc/html/rfc7322#section-4.1.1
>    [3] https://chairs.ietf.org/documents/qa-style-writeup-template
> =====
> 
> 
> 
> ...
>> * Question 15 - Again, a link to guidance would be helpful.
> 
>    15. Should any informative references be normative or vice-versa?
> 
> There's an IESG statement for that: ;-)
> 
> https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
> 
> 
> Thanks!
> 
> Alvaro.

--
Mark Nottingham   https://www.mnot.net/