[rfc-i] Style Guide and Abstract guidance

Martin J. Dürst duerst at it.aoyama.ac.jp
Sun Sep 10 21:42:08 PDT 2017


On 2017/09/11 07:18, Martin Thomson wrote:
> 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.

The text below explicitly says:

                       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.

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.


> On Sat, Sep 9, 2017 at 1:57 AM, Heather Flanagan (RFC Series Editor)
> <rse at rfc-editor.org> wrote:
>> 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
>> rfc-interest at rfc-editor.org
>> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
> .
> 

-- 
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


More information about the rfc-interest mailing list