On 9/12/18 7:45 AM, Paul Hoffman wrote:
On 12 Sep 2018, at 7:33, Sean Turner wrote:
The specific reasons that a given RFC updates another should be
described in the abstract and body of the new RFC. The level of
detail may differ between the abstract and the body; typically an
abstract should contain enough detail to help readers decide if they
need to read the rest of the RFC. The body should contain enough
detail for readers to fully understand the nature of the update.
I like to say that I hate the whole list the reasons why in the
abstract. I understand that we also say what RFCs are updated in the
abstract because there are some tools that don’t display the
meta-data and that we do it so readers will know whether or not to
keep reading. That’s great for an RFC that’s updating one RFC and it
keeps in line with keep the abstract succinct plus the boiler plate
on the 1st page. But, when you’ve got an RFC that’s going to update
say eight (8) RFCs that this is kinda crazy.
Sean's exactly right here. Having to add a lot of new text to the
abstract basically makes it a mini-introduction. Instead, please
consider:
The specific reasons that a given RFC updates another should be
described near the top of the Introduction section of the new RFC,
possibly in its own sub-section. This text should contain enough
detail to help readers who are familiar with the specification that is
being updated to decide if they need to read the rest of this newer
RFC. This text must contain enough detail for readers to fully
understand the nature of the update.
I think this is a very reasonable approach. The abstract should
definitely be succinct, and text explaining the relationship of one RFC
to another (or set of others) should exist, too, but I see it necessary
that it exists in the abstract itself. Put it in the introduction or put
it in its own section if the relationships are complicated enough to
need a roadmap of some type.
-Heather
