Subject: Document shepherd writeup formats

From: Jim Fenton <[email-masked]>
Date: Mon, 25 Nov 2019 13:22:06 -0800

I just completed a document shepherd writeup in the "newer essay-style
version" described on the DocumentShepherding page of the Chairs' wiki.
But when I went to submit it, the form popped up with a template for the
question-and-answer format, which led me to believe that format is
preferred.

Is the essay-style format actually preferred? I'm wondering if it's a
good idea to have two writeup formats rather than a single one. Or do
preferences vary by AD?

-Jim

---

From: Yoav Nir <[email-masked]>
Date: Mon, 25 Nov 2019 23:38:53 +0200

> On 25 Nov 2019, at 23:22, Jim Fenton <[email-masked]> wrote:
> 

I prefer the essay form. In my opinion, use whichever one you prefer, unless your AD yells at you.

IIRC this started out as Barry Leiba’s idea, 

Yoav

---

From: Alexey Melnikov <[email-masked]>
Date: Tue, 26 Nov 2019 06:23:23 +0000

Hi Jim,

> On 25 Nov 2019, at 21:22, Jim Fenton <[email-masked]> wrote:
> 

Yes :-)

For new WG chairs I prefer the question-and-answer format. In my experience new shepherds miss lots of checks which AD has to do if essay-style is used.

When doing essay-style I also ask my chairs to mention existing and/or expected deployments (unless there is a section in the document), as this information is needed in IESG ballot and is frequently missing in essay-style writeup.

Best Regards,
Alexey

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 26 Nov 2019 10:46:13 +0100

> For new WG chairs I prefer the question-and-answer format. In my experience new shepherds miss lots of checks which AD has to do if essay-style is used.

This not so new WG chair prefers the question-and-answer format for exactly the same reason pilots like checklists.

Grüße, Carsten

---

From: G Fairhurst <[email-masked]>
Date: Tue, 26 Nov 2019 09:56:27 +0000

On 26/11/2019, 09:46, Carsten Bormann wrote:
> On Nov 26, 2019, at 07:23, Alexey Melnikov<[email-masked]>  wrote:
+1

Gorry

---

From: Tim Chown <[email-masked]>
Date: Tue, 26 Nov 2019 11:26:49 +0000

> On 26 Nov 2019, at 09:56, G Fairhurst <[email-masked]> wrote:
> 

I agree - the Q&A format is my preference.

Tim

---

From: Margaret Cullen <[email-masked]>
Date: Tue, 26 Nov 2019 08:47:15 -0500

Even as an experienced chair/shepherd, I have found the Q&A style form to be a useful checklist to make sure I have done everything I should do before forwarding the document to the AD.

Margaret

> On Nov 26, 2019, at 6:26 AM, Tim Chown <[email-masked]> wrote:
>

---

From: "Andrew G. Malis" <[email-masked]>
Date: Tue, 26 Nov 2019 09:01:21 -0500

I also prefer the Q&A form for the same reason.

Cheers,
Andy

On Tue, Nov 26, 2019 at 8:47 AM Margaret Cullen <[email-masked]>
wrote:

> Even as an experienced chair/shepherd, I have found the Q&A style form to
> be a useful checklist to make sure I have done everything I should do
> before forwarding the document to the AD.
>
> Margaret
>
> >>>> For new WG chairs I prefer the question-and-answer format. In my
> experience new shepherds miss lots of checks which AD has to do if
> essay-style is used.
> >>> This not so new WG chair prefers the question-and-answer format for
> exactly the same reason pilots like checklists.
> >>>
> >>> Grüße, Carsten
> >> +1
> >

---

From: Bob Hinden <[email-masked]>
Date: Tue, 26 Nov 2019 08:33:38 -0800

I also prefer the Q&A form for the same reasons.

Bob

> On Nov 26, 2019, at 6:01 AM, Andrew G. Malis <[email-masked]> wrote:
> 
> On Tue, Nov 26, 2019 at 8:47 AM Margaret Cullen <[email-masked]> wrote:

---

From: Job Snijders <[email-masked]>
Date: Tue, 26 Nov 2019 09:06:41 -0800

I like the newer essay style.

But what are we trying to solve in this thread? A straw poll on what our
favorite color is? :-)

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2019 17:20:07 +0000

I submit the essay form, after using the checklist form to be sure I have done everything. Most often missed for me: IPR question to the authors.

--Paul Hoffman

---

From: Benjamin Kaduk <[email-masked]>
Date: Tue, 26 Nov 2019 10:37:09 -0800

> But what are we trying to solve in this thread? A straw poll on what our

I think we're trying to ascertain whether the essay style has just been a
mass hallucination or silently deprecated or something like that.  (AFAIK,
the answer is "no".)

I see the current Q&A template is dated 1 November 2019; I wonder if that
update inadvertently removed some text that mentioned the essay-style
template.  (Or perhaps I was just hallucinating that it ever existed...)

-Ben

---

From: Robert Sparks <[email-masked]>
Date: Tue, 26 Nov 2019 14:48:58 -0600

> template.  (Or perhaps I was just hallucinating that it ever existed...)

The update did not remove any text that mentioned the essay-style template.

You can see before/after using this changeset:

https://trac.tools.ietf.org/tools/ietfdb/changeset/16991

It's easiest to parse if you select the side-by-side diff.

RjS