Subject: [Taps] One RFC, or two, for draft-ietf-taps-transports-usage and draft-ietf-taps-transports-usage-udp

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 13 Sep 2017 23:47:04 -0500

Dear TAPS working group,

Multiple ADs have asked why these two drafts aren't a single draft, in
their ballots. Those are non-blocking comments, but I'd like to explore
that, before making a decision about what should happen, and when.

It occurs to me that these ADs are reading both drafts pretty much
back-to-back in preparation for balloting during IESG Evaluation.

If people reading the two drafts back-to-back find the split to be a
distraction, I'd like to understand the views of the working group as to
how often you expect people to read both drafts, in order to do TAPS.

I could imagine that people working on complete TAPS APIs might need to
read both drafts.

What about other folks you expect to read these documents? Do you expect
that some communities only need to read one of them?

Thanks in advance for any thoughts you can share.

Spencer, as responsible AD for TAPS

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Thu, 14 Sep 2017 09:55:52 -0500

And, following up during the actual telechat ...

> Spencer, as responsible AD for TAPS

Both documents were approved on the telechat today, pending comment
resolution of comments received during IESG Evaluation.

So, my request to the working group to consider whether the suggestion to
combine these documents makes life easier for the readers you expect will
need to read one, the other, or both documents REALLY IS an honest
question, and not the IESG requiring fabulously late major editorial
changes without an active Discuss, because That Would Be Wrong.

Either answer works. We'll Do The Right Thing.

"Thanks in advance for your thoughts" :-)

Spencer, as responsible AD, who the IESG said they trusted to "Do The Right
Thing"

---

From: Gorry Fairhurst <[email-masked]>
Date: Thu, 14 Sep 2017 17:02:29 +0100

On 14/09/2017, 15:55, Spencer Dawkins at IETF wrote:
> On Wed, Sep 13, 2017 at 11:47 PM, Spencer Dawkins at IETF 
> <[email-masked] <mailto:[email-masked]>> 
> wrote:
>
>     Dear TAPS working group,
>
>     Multiple ADs have asked why these two drafts aren't a single
>     draft, in their ballots. Those are non-blocking comments, but I'd
>     like to explore that, before making a decision about what should
>     happen, and when.
>
>     If people reading the two drafts back-to-back find the split to be
>     a distraction, I'd like to understand the views of the working
>     group as to how often you expect people to read both drafts, in
>     order to do TAPS.
>
>     I could imagine that people working on complete TAPS APIs might
>     need to read both drafts.
>
>     What about other folks you expect to read these documents? Do you
>     expect that some communities only need to read one of them?
>
> So, my request to the working group to consider whether the suggestion 
> to combine these documents makes life easier for the readers you 
> expect will need to read one, the other, or both documents REALLY IS 
> an honest question, and not the IESG requiring fabulously late major 
> editorial changes without an active Discuss, because That Would Be Wrong.
>
> Spencer, as responsible AD, who the IESG said they trusted to "Do The 
> Right Thing"
>
>
> _______________________________________________
> Taps mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/taps

There was a proposal from IESG to consider whether we should merge the 
two usage documents. So after giving this some more thought, here is my 
2c about why I think we should keep the two documents:

First, I accept it may be easier for someone reviewing the history of 
TAPS and the rationale for design decisions to read just a single 
document - putting all the material in one place is always easier. 
However, if published in consecutive RFCs, I'm not convinced the 
material would be really hard for a reader to find.

I suggested there were two reasons behind separating this out when we 
did the work. First, the old and incomplete documentation for UDP needed 
a slightly different approach to finding the relevent RFCs. Second, the 
community of interest in using UDP at the IETF is typically to be found 
outside the TSV area, partly because of the wide variety of uses. A 
second document made this easier for these people to read. That's still 
the case for the material that was retained in the UDP usage document.

It would be my hope that the UDP document could form a long-needed part 
of the documentation for UDP. I expect this would continue to be a 
useful resource for anyone who wishes to build datagram support into a 
new stack, or just wants to program to this API, and avoids people 
needing to wade through 50-60 pages to find a section on a UDP API. I'd 
also hope (??!!) this document could be maintained in future as the API 
continues to develop.

Gorry

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 18 Sep 2017 11:05:29 -0500

Dear TAPSters,

On Thu, Sep 14, 2017 at 11:02 AM, Gorry Fairhurst <[email-masked]>
wrote:

>> [email-masked] <mailto:[email-masked]>>
>> wrote:
>>
>>     Dear TAPS working group,
>>
> There was a proposal from IESG to consider whether we should merge the two
> usage documents. So after giving this some more thought, here is my 2c
> about why I think we should keep the two documents:
>
> First, I accept it may be easier for someone reviewing the history of TAPS
> and the rationale for design decisions to read just a single document -
> putting all the material in one place is always easier. However, if
> published in consecutive RFCs, I'm not convinced the material would be
> really hard for a reader to find.
>
> I suggested there were two reasons behind separating this out when we did
> the work. First, the old and incomplete documentation for UDP needed a
> slightly different approach to finding the relevent RFCs. Second, the
> outside the TSV area, partly because of the wide variety of uses. A second
> document made this easier for these people to read. That's still the case
> for the material that was retained in the UDP usage document.
>
> It would be my hope that the UDP document could form a long-needed part of
> the documentation for UDP. I expect this would continue to be a useful
> resource for anyone who wishes to build datagram support into a new stack,
> or just wants to program to this API, and avoids people needing to wade
> through 50-60 pages to find a section on a UDP API. I'd also hope (??!!)
> this document could be maintained in future as the API continues to develop.
>
> Gorry
>

Gorry's e-mail captured pretty much everything I need to know. I have one
more question, because I know that people have implemented TAPSish APIs and
demonstrated them.

If you worked on one of those APIs, did you have to read both documents?

Thanks in advance, and asking for (14) friends ...

Spencer, as responsible AD

---

From: Tommy Pauly <[email-masked]>
Date: Wed, 20 Sep 2017 19:31:33 -0700

Hi Spencer,

As an API implementer, I would say this:

- I did need to reference the content of both documents (or the equivalent information that is included in the documents, before they were complete) in our implementation
- However, implementing the API details for unconnected datagram-based protocols and connected stream-based is very different, even if they reside behind a common interface. To that end, both documents are necessary, but can be looked at separately while implementing an API for the protocols. I could imagine splitting up work between implementers to each focus on one of the documents, without needing to reference the other excessively.

Thanks,
Tommy

> On Sep 18, 2017, at 9:05 AM, Spencer Dawkins at IETF <[email-masked]> wrote:
> 
> Dear TAPSters,
> 
> On Thu, Sep 14, 2017 at 11:02 AM, Gorry Fairhurst <[email-masked] <mailto:[email-masked]>> wrote:
> On Wed, Sep 13, 2017 at 11:47 PM, Spencer Dawkins at IETF <[email-masked] <mailto:[email-masked]> <mailto:[email-masked] <mailto:[email-masked]>>> wrote:
> 
>     Dear TAPS working group,
> 
> Both documents were approved on the telechat today, pending comment resolution of comments received during IESG Evaluation.
> 
> So, my request to the working group to consider whether the suggestion to combine these documents makes life easier for the readers you expect will need to read one, the other, or both documents REALLY IS an honest question, and not the IESG requiring fabulously late major editorial changes without an active Discuss, because That Would Be Wrong.
> 
> Spencer, as responsible AD, who the IESG said they trusted to "Do The Right Thing"
> 
> 
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/taps <https://www.ietf.org/mailman/listinfo/taps>
> 
> There was a proposal from IESG to consider whether we should merge the two usage documents. So after giving this some more thought, here is my 2c about why I think we should keep the two documents:
> 
> First, I accept it may be easier for someone reviewing the history of TAPS and the rationale for design decisions to read just a single document - putting all the material in one place is always easier. However, if published in consecutive RFCs, I'm not convinced the material would be really hard for a reader to find.
> 
> I suggested there were two reasons behind separating this out when we did the work. First, the old and incomplete documentation for UDP needed a slightly different approach to finding the relevent RFCs. Second, the community of interest in using UDP at the IETF is typically to be found outside the TSV area, partly because of the wide variety of uses. A second document made this easier for these people to read. That's still the case for the material that was retained in the UDP usage document.
> 
> It would be my hope that the UDP document could form a long-needed part of the documentation for UDP. I expect this would continue to be a useful resource for anyone who wishes to build datagram support into a new stack, or just wants to program to this API, and avoids people needing to wade through 50-60 pages to find a section on a UDP API. I'd also hope (??!!) this document could be maintained in future as the API continues to develop.
> 
> Gorry
> 
> Gorry's e-mail captured pretty much everything I need to know. I have one more question, because I know that people have implemented TAPSish APIs and demonstrated them. 
> 
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/taps <https://www.ietf.org/mailman/listinfo/taps>

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 20 Sep 2017 22:00:11 -0500

Hi, Tommy

On Wed, Sep 20, 2017 at 9:31 PM, Tommy Pauly <[email-masked]> wrote:

> - I did need to reference the content of both documents (or the equivalent
> information that is included in the documents, before they were complete)
> in our implementation
> - However, implementing the API details for unconnected datagram-based
> protocols and connected stream-based is very different, even if they reside
> behind a common interface. To that end, both documents are necessary, but
> can be looked at separately while implementing an API for the protocols. I
> could imagine splitting up work between implementers to each focus on one
> of the documents, without needing to reference the other excessively.
>

This is the other half of the input I needed. Thanks for that.

My theory was that most readers would not be reading both documents
back-to-back, but that's the way ADs would review the documents during IESG
Evaluation (they were even on the same telechat). So it's more disorienting
for us, than for pretty much anyone else :-)

Spencer

>>> to combine these documents makes life easier for the readers you expect
>>> will need to read one, the other, or both documents REALLY IS an honest
>> two usage documents. So after giving this some more thought, here is my 2c
>> TAPS and the rationale for design decisions to read just a single document
>> - putting all the material in one place is always easier. However, if
>> of the documentation for UDP. I expect this would continue to be a useful