Subject: [rfc-i] Style Guide and Abstract guidance

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 8 Sep 2017 08:57:28 -0700

Hello all,

After some discussion with the IESG, I'm proposing a substantive change
to the guidance around Abstracts. The goal is to make the Abstract more
clear in setting the context of the document. I'd like community
feedback before I update the draft. Thoughts?

CURRENT:
4.3.  Abstract Section

   Every RFC must have an Abstract that provides a concise and
   comprehensive overview of the purpose and contents of the entire
   document, to give a technically knowledgeable reader a general
   overview of the function of the document.

   Composing a useful Abstract generally requires thought and care.
   Usually, an Abstract should begin with a phrase like "This memo ..."
   or "This document ..."  A satisfactory Abstract can often be
   constructed in part from material within the Introduction section,
   but an effective Abstract may be shorter, less detailed, and perhaps
   broader in scope than the Introduction.  Simply copying and pasting
   the first few paragraphs of the Introduction is allowed, but it may
   result in an Abstract that is both incomplete and redundant.  Note
   also that an Abstract is not a substitute for an Introduction; the
   RFC should be self-contained as if there were no Abstract.

   Similarly, the Abstract should be complete in itself.  It will appear
   in isolation in publication announcements and in the online index of
   RFCs.  Therefore, the Abstract must not contain citations.

PROPOSED:
4.3.  Abstract Section

   Every RFC must have an Abstract that provides a concise and
   comprehensive overview of the purpose and contents of the entire
   document, to give a technically knowledgeable reader a general
   overview of the function of the document and some context with
   regards to its relationship (in particular, whether it updates or
   obsoletes) any other RFCs.  In addition to its function in the RFC
   itself, the Abstract section text will appear in publication
   announcements and in the online index of RFCs.

   Composing a useful Abstract generally requires thought and care.
   Usually, an Abstract should begin with a phrase like "This memo ..."
   or "This document ..."  A satisfactory Abstract can often be
   constructed in part from material within the Introduction section,
   but an effective Abstract may be shorter, less detailed, and perhaps
   broader in scope than the Introduction.  Simply copying and pasting
   the first few paragraphs of the Introduction is allowed, but it may
   result in an Abstract that is overly long, incomplete, and redundant.

   An Abstract is not a substitute for an Introduction; the
   RFC should be self-contained as if there were no Abstract.
   Similarly, the Abstract should be complete in itself.  Given that the
   Abstract will appear independently in announcements
   and indices, mentions of other RFCs within the Abstract should
   include both an RFC number and  title.  If a short description
   is clearer than the literal title, it may be included in addition
   or instead.  Any documents that are Updated or Obsoleted by the RFC
   must be mentioned in the Abstract.  These may be presented in a
   list format if that improves readability

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Bob Hinden <[email-masked]>
Date: Fri, 8 Sep 2017 09:22:23 -0700

Heather,

Looks fine to me.

If it’s helpful, a side by side diff is attached.

Bob

> On Sep 8, 2017, at 8:57 AM, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> Hello all,
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 8 Sep 2017 18:41:39 +0200

Generally looks good.

On Sep 8, 2017, at 17:57, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> mentions of other RFCs within the Abstract should
>    include both an RFC number and  title.

This no longer says “no citations”; it just talks about RFCs.
I don’t think citations such [802.1AR-2009] should be in abstracts.

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 9 Sep 2017 08:38:37 +1200

> I don’t think citations such [802.1AR-2009] should be in abstracts.

I agree with that. However, I suggest considering
s/title/title or abbreviated title/.

If you want to mention RFC 1129 in an Abstract, it should be
sufficient to say "Network Time Protocol", not waste space with
"Internet Time Synchronization: The Network Time Protocol".

Also, could we have a "No Politics" rule for abstracts?
There was an I-D recently whose abstract said:
"The network operator and vendor community has clearly indicated that
<proposed feature> is useful and required."

    Brian

---

From: Adam Roach <[email-masked]>
Date: Fri, 8 Sep 2017 16:00:00 -0500

On 9/8/17 10:57 AM, Heather Flanagan (RFC Series Editor) wrote:
>     obsoletes) any other RFCs.

I think this sentence needs a bit of editing to be grammatical: if you 
remove the parenthetical phrase, it becomes obvious that the final 
prepositional phrase lacks a preposition (in large part because the main 
sentence treats the final three words as a prepositional phrase while 
the parenthetical phrase treats them as a direct object). I could make a 
suggestion, but I'm sure you have more experience editing English than I 
do. :)

/a

---

From: Martin Thomson <[email-masked]>
Date: Mon, 11 Sep 2017 08:18:56 +1000

I hope that the omission of a final period is just a copy-paste error.

The requirement to include an RFC title will make things more
cumbersome.  I agree with Brian that allowing an abbreviated title
would be wise.  A recent document has a title that consumes two lines
on its own.

---

From: Martin J. Dürst <[email-masked]>
Date: Mon, 11 Sep 2017 13:42:08 +0900

> would be wise.  A recent document has a title that consumes two lines

The text below explicitly says:

    or instead.

If the title consumes two lines, then a short description may be shorter 
(and clearer :-) than the title, and can be used instead. So I think we 
are covered. But of course, the text can still be improved.

Regards,    Martin.

> .

-- 
Prof. Dr.sc. Martin J. Dürst
Department of Intelligent Information Technology
College of Science and Engineering
Aoyama Gakuin University
Fuchinobe 5-1-10, Chuo-ku, Sagamihara
252-5258 Japan
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 12 Sep 2017 16:36:21 -0700

On 9/10/17 9:42 PM, Martin J. Dürst wrote:
> If the title consumes two lines, then a short description may be
> shorter (and clearer :-) than the title, and can be used instead. So I
> think we are covered. But of course, the text can still be improved.

Thanks, all. This has been helpful, and a revised draft has now been posted.

https://datatracker.ietf.org/doc/draft-flanagan-7322bis/

-Heather