Re: I-D Action: draft-roach-bis-documents-00.txt

[Adam Roach <[e-mail]>]

On 5/8/19 5:50 AM, Martin Thomson wrote:
> BTW, I really like where this is going.  We need more ways to smooth the path toward maintaining protocols (see what I did there?).
>
> In the spirit of providing feedback on the document as written...
>
> On Wed, May 8, 2019, at 12:50, Adam Roach wrote:
>> Thanks for noticing and providing proactive feedback.
>     2.  The changes from the document being obsoleted must not constitute
>         the majority of the document.  This is a subjective evaluation,
>         not a mathematical one.
>
> I think that there is case for assessing a "substantial portion of the document or a significant technical change" rather than "majority of the document" test here.  That makes the call even more subjective, but I don't believe that it would be appropriate to pass something that changed fundamental concepts without thorough review.  For instance, it might be possible to amend the definition of dialog-forming requests in SIP without hitting enough of RFC 3261 to meet a "majority" test, but publication of a change like that under the proposed process is not likely to be appropriate.


That's a good point, and captures more of what I really wanted to convey 
here. I've rephrased as:

2. The changes from the document being obsoleted must not constitute
    the majority of the document, nor must they be a fundamental technical
    change to its underlying mechanism. This is a subjective evaluation,
    not a mathematical one.


>
>     4.  The document SHOULD contain an appendix detailing the changes
>         from the RFC it is replacing.  Any change for which the rationale
>         is not abundantly obvious should be explained in this appendix.
>
> I don't see why an appendix is stipulated.  Concise descriptions of changes in introductory sections are often a very welcome way to explain differences.


I'm not married to the notion of an appendix, but I think the 
description of changes benefits greatly from being in a dedicated 
section -- and since it doesn't really form the core of the document, 
having it as an appendix seems like the right kind of thing. To your 
specific suggestion: like every other section, unless the introduction 
otherwise requires revision, I'd like to avoid seeing changes made to it.

Backing up to some of the philosophy of what I'm trying to accomplish: 
I'd like to see bis documents as taking our initial pass(es) at a 
protocol and bringing them closer to the platonic ideal of what that 
document might have been in the first place, with the benefit of 
experience and hindsight [1]. For any useful protocol we've developed so 
far, the future is bigger than the past, and my goal is to give 
developers in the future a better document that doesn't look like some 
kind of patchwork quilt. Wedging additional text into the body like you 
propose doesn't really accomplish this.


>
>    3. The "Last-Call notification" MUST also include a pointer to a
>         mechanically-generated diff [...]
>
> This is good, but you might make it easier by citing the section that summarizes changes.


Good point. I've added that.


> Section 3.3 is I think the most difficult part of this.  I agree with you that finding a way to be able to publish a document without touching certain outdated pieces is very important, but I think that your solution contains another problem.
>
> If some things are controversial, we might find that even listing things that don't follow best practice to be difficult.  I would instead suggest that rather than requiring enumeration of all the "icky bits", we instead label what is updated and say that "everything else is left as is and might not reflect current best practice".  That is,
>
>       This document is a revision of a previously published RFC. Those
>       portions of the text that have not been updated might not meet
>       current best practices for documents published by the IETF.
>
> I know that this is weaker than what you are proposing, but it should avoid having people avoid updates where there are these booby traps.  I'm happy if you encourage the listing of things that are especially problematic, but you use the "m" word... which creates a barrier.


I've had several conversations with standing and former members of the 
IESG about the overall proposal I present in this document, and more 
than one person got hung up on the notion of letting 
known-to-be-deprecated approaches through without comment. Largely, 
these involve issues that have already been documented in BCP  or 
Standards Track documents, and which would otherwise constitute DISCUSS 
criteria. Cast in that light, I think the enumeration of what would be 
different in a green-field protocol is actually quite important, 
although I concede that the current text might not capture it as clearly 
as I like.


> (in lowercase, which I don't quite follow)


It's a -00 version, and I haven't gone through to double-check my 2119 
terms. I'll rationalize these in a future version.


> Now, I would prefer that people work through those controversial points, but I've seen enough good work stymied by bickering over unimportant or unrelated points that some caution might be wise.


I would definitely prefer that such points be worked through as well 
(and say as much in the "Security Considerations" section, as many such 
controversial points fall into the security area). I take your point 
that even agreeing on what is a Bad Idea might cause some heartburn, but 
I don't think a blanket "something in here might be wrong, but we won't 
tell you what" statement accomplishes much at all.


> Finally, you might consider promoting the real content from Section 6 to the body of the document.
>

Good point. Done.

/a


____
[1] There's also a goal to make the documents easy to review and easy to 
approve that drives the desire to eliminate spurious changes, but this 
is done in service to getting an improved document out as quickly as 
possible.