Re: [Taps] Normative language change in the Interface document (Re: I-D Action: draft-ietf-taps-interface-19.txt)

[Michael Welzl <[e-mail]>]

Hi Brian,

This PR has been waiting for your reaction for a while:
https://github.com/ietf-tapswg/api-drafts/pull/1125 <https://github.com/ietf-tapswg/api-drafts/pull/1125>

One out of two remaining PRs … after these, we should probably issue a new version.

Cheers,
Michael


> On Mar 10, 2023, at 5:55 PM, Brian Trammell (IETF) <[e-mail]> wrote:
> 
> Adding a sentence making it clear it’s safe to skip the glossary if you’re going to read the rest of the document would address my approachability concern completely. :)
> 
> Sent from my iPhone
> 
>> On 10 Mar 2023, at 17:34, Gorry Fairhurst <[e-mail]> wrote:
>> 
>> On 10/03/2023 14:57, Brian Trammell (IETF) wrote:
>>> hi Reese, all,
>>> 
>>> Apologies I haven’t been around on the answering-of-comments; it’s been a rough month. Thanks, all, for getting these revs of the documents out. I’ve reviewed the changes.
>>> 
>>> - Arch changes are good, modulo the following non-blocking comment:
>>> 
>>> I’m not convinced of the value of the glossary of terms, as it forwardrefs basically the entire document, and some of the definitions are so generic as to be potentially confusing (e.g. Event), so I think putting these up front reduces the document’s approachability and readability.  I understand that some people like these (and other standards orgs make them mandatory, hi ETSI), so I won’t fight it.
>> 
>> Mea cupla on this, and I did recall your thoughts when we discussed at one of the TAPS interims. At first I didn't feel persauded, but as I tried to reset my head to someone who had never read these IDs before, I began to think this could be really valuable to give some initial context to the many terms we use across the documents. The text is identical or "thinned" versions of later text.
>> 
>> If this glossary is thought useful - which I now personally think it is, but others are free to comment  - I'd be really quite OK with this "glossary" starting with a sentence that says each of these terms is defined later in the document, in other words - hinting strongly don't bother with this if you know what you are reading....
>> 
>>> 
>>> - Interface changes are good.
>>> 
>>> - Implementation changes are good.
>>> 
>>> Cheers,
>>> 
>>> Brian
>>> 
>>>>> On 10 Mar 2023, at 01:26, Reese Enghardt <[e-mail]> wrote:
>>>> 
>>>> Dear TAPS,
>>>> 
>>>> As you may have seen, our three documents were updated to address Zahed's AD review comments (Thank you to everyone involved!).
>>>> 
>>>> Please note that there were normative language changes in the Interface document.
>>>> 
>>>> If you have any questions about or any objections to these changes, please respond to the list within the next two weeks, i.e., by Thursday March 23rd, 5pm PT. (This is Thursday before IETF 116.)
>>>> 
>>>> If we don't hear anything by this date, we will assume that there is WG consensus on these changes.
>>>> 
>>>> For your convenience, here are the diffs for all three documents:
>>>> 
>>>> 
>>>> https://author-tools.ietf.org/iddiff?url2=draft-ietf-taps-arch-16
>>>> 
>>>> https://author-tools.ietf.org/iddiff?url2=draft-ietf-taps-interface-19
>>>> 
>>>> https://author-tools.ietf.org/iddiff?url2=draft-ietf-taps-impl-15
>>>> 
>>>> 
>>>> Best,
>>>> Reese
>>>> 
>>>> 
>>>> On 3/9/23 10:01, [e-mail] wrote:
>>>>> A New Internet-Draft is available from the on-line Internet-Drafts directories.
>>>>> This Internet-Draft is a work item of the Transport Services WG of the IETF.
>>>>> 
>>>>>        Title           : An Abstract Application Layer Interface to Transport Services
>>>>>        Authors         : Brian Trammell
>>>>>                          Michael Welzl
>>>>>                          Theresa Enghardt
>>>>>                          Godred Fairhurst
>>>>>                          Mirja Kuehlewind
>>>>>                          Colin Perkins
>>>>>                          Philipp S. Tiesel
>>>>>                          Tommy Pauly
>>>>>  Filename        : draft-ietf-taps-interface-19.txt
>>>>>  Pages           : 91
>>>>>  Date            : 2023-03-09
>>>>> 
>>>>> Abstract:
>>>>>   This document describes an abstract application programming
>>>>>   interface, API, to the transport layer that enables the selection of
>>>>>   transport protocols and network paths dynamically at runtime.  This
>>>>>   API enables faster deployment of new protocols and protocol features
>>>>>   without requiring changes to the applications.  The specified API
>>>>>   follows the Transport Services architecture by providing
>>>>>   asynchronous, atomic transmission of messages.  It is intended to
>>>>>   replace the BSD sockets API as the common interface to the transport
>>>>>   layer, in an environment where endpoints could select from multiple
>>>>>   interfaces and potential transport protocols.
>>>>> 
>>>>> 
>>>>> The IETF datatracker status page for this Internet-Draft is:
>>>>> https://datatracker.ietf.org/doc/draft-ietf-taps-interface/
>>>>> 
>>>>> There is also an HTML version available at:
>>>>> https://www.ietf.org/archive/id/draft-ietf-taps-interface-19.html
>>>>> 
>>>>> A diff from the previous version is available at:
>>>>> https://author-tools.ietf.org/iddiff?url2=draft-ietf-taps-interface-19
>>>>> 
>>>>> 
>>>>> Internet-Drafts are also available by rsync at rsync.ietf.org::internet-drafts
>>>>> 
>>>>> 
>>>>> _______________________________________________
>>>>> Taps mailing list
>>>>> [e-mail]
>>>>> https://www.ietf.org/mailman/listinfo/taps
>>>>> 
>>>> _______________________________________________
>>>> Taps mailing list
>>>> [e-mail]
>>>> https://www.ietf.org/mailman/listinfo/taps
>>> _______________________________________________
>>> Taps mailing list
>>> [e-mail]
>>> https://www.ietf.org/mailman/listinfo/taps
>> 
>> 
> 
> _______________________________________________
> Taps mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/taps