Subject: Re: [rfc-i] rfc-interest Digest, Vol 196, Issue 22

From: John C Klensin <[email-masked]>
Date: Mon, 22 Feb 2021 17:53:56 -0500

--On Monday, February 22, 2021 13:10:44 -0600 Robert Sparks
<[email-masked]> wrote:

> On 2/22/21 2:15 AM, Carsten Bormann wrote:
>> On 22. Feb 2021, at 08:35, Julian Reschke
>> <[email-masked]> wrote:
>>> Note that the recommendations are inconsistent, and that the
>>> first one (from the web site) adds a link to tools.ietf.org.
>> ? which has served us well as a landing page for a draft.
>> 
>> People like that page a lot because it has the relevant
>> metadata and links as well as the content of the draft.
>> 
>> (The equivalent data tracker page has more, but less useful
>> and less usefully presented metadata, and it only has the
>> first two pages of the draft, because it was *not* designed
>> to serve as the landing page.)
> 
> Minor, but important note - it only shows the first two pages
> by default  for concern (at the time it was made) about
> bandwidth for consumers -  the site does allow you to control
> getting the whole draft on that page  by cookie. I realize
> that's not useful (or is a negative) for making it  the URL
> you might cite. But perhaps we should revisit at least the
> first  part of the document cookie and either always serve the
> whole document  there, or flip the default to always serve.
> 
> That said, the page you are looking for is probably going to be
> 
> datatracker.ietf.org/doc/html/(whatever)
> 
> I am in the middle of significantly changing that to have the
> same  information in the header as the draft pages at tools,
> remove the normal  datatracker nav menu and tabs, and to
> follow the same general formatting  style in what's at tools.

I am having trouble completely picturing just what you have in
mind, but, whatever you do, please keep in mind that references
from RFCs are supposed to be completely stable.  That means
that, if I, as author, reference draft-foo-bar-baz-03 at the
time of RFC publication, wherever the link points should produce
draft-foo-bar-baz-03 and not its most recent successor, whether
that is draft-foo-bar-baz-15 or RFC 9999.  This is, of course a
cousin of whether a new I-D or RFC should be referencing the
same target RFC as the document it is replacing or should be
referencing the most recent update/replacement for that earlier
version.  In both cases, heuristics will frequently be wrong.
It might actually be useful for authors to be able to specify
"the version we specified, really" versus "most recent version"
in markup.

I'm even a little hesitant about your pointing to the HTML
version as long as at least some of the html versions are
synthesized from the text rather than being supplied by authors
(who have presumably checked them) or generated from xml2rfc v3
(which is presumably infallible). The synthesis process doesn't
make serious errors very often, but, in my experience, it does
make them.

best,
    john

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 23 Feb 2021 01:39:33 +0100

> that is draft-foo-bar-baz-15 or RFC 9999.  

Yes, but the landing page for -03 could have pointers to newer versions (I-D, RFC, Obsoleting RFC, …).

> This is, of course a

Which you already can do in the source for an I-D.  RFC references are frozen, though.

> make serious errors very often, but, in my experience, it does

This could easily be fixed.
I did a PoC for that a while ago.
The data collection for the fixer does need some effort; this could be crowd-sourced or done proactively (probably more expensive than we care about this problem).

Grüße, Carsten

---

From: John C Klensin <[email-masked]>
Date: Mon, 22 Feb 2021 22:41:31 -0500

--On Tuesday, February 23, 2021 01:39 +0100 Carsten Bormann
<[email-masked]> wrote:

>> mind, but, whatever you do, please keep in mind that
>> references from RFCs are supposed to be completely stable.
>> That means that, if I, as author, reference
>> draft-foo-bar-baz-03 at the time of RFC publication, wherever
>> the link points should produce draft-foo-bar-baz-03 and not
>> its most recent successor, whether that is
>> draft-foo-bar-baz-15 or RFC 9999.  
> 

I have no problem with that as long as the landing page
unambiguously gets the reader to -03.  The current datatracker
page for a draft does not have that property -- one gets a
multiversion page that shows the most recent one and then has to
figure out how to navigate back to a particular version.

>> referencing the most recent update/replacement for that
>> earlier version.  In both cases, heuristics will frequently
>> be wrong. It might actually be useful for authors to be able
>> to specify "the version we specified, really" versus "most
>> recent version" in markup.
> 

I probably missed how to do that in I-Ds referencing I-Ds after
I got frustrated many years ago with automated handling of them
and just started typing them in.  

>> synthesized from the text rather than being supplied by
>> authors (who have presumably checked them) or generated from
>> xml2rfc v3 (which is presumably infallible). The synthesis
>> process doesn't make serious errors very often, but, in my
>> experience, it does make them.

> The data collection for the fixer does need some effort; this
> could be crowd-sourced or done proactively (probably more
> expensive than we care about this problem).

Personally, I'd much rather see any spare energy in the short
term concentrated on fixing things like indexes.

best,
   john

---

From: tom petch <[email-masked]>
Date: Tue, 23 Feb 2021 12:16:46 +0000

> figure out how to navigate back to a particular version.

For me, the datatracker page that I get to from a datatracker WG page 
has the metadata that I need to work, whereas the tools page is sadly 
lacking in that regard.  Yes, there is less metadata but I need that 
missing metadata so leaving it out is counter-productive.

Also, from https://datatracker.ietf.org/doc/<i-d name> I get what is to 
me a clear display of the document history from which I can navigate to 
(almost) any earlier version.  I am puzzled that there should be any 
difficulty in clicking on the green or purple bar to select a different 
version (except when the submissions window is closing and authors 
submit three versions in under 24 hours and the bars shrink to zero).

I think that the datatracker took a giant leap forward at some point 
from being unusable to being the best way into the work of the IETF so 
my home page became Active WGs. I often want to return there so that 
having the nav bar is most useful.

Tom Petch

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 23 Feb 2021 14:35:35 +0100

> 
> For me, the datatracker page that I get to from a datatracker WG page has the metadata that I need to work, whereas the tools page is sadly lacking in that regard.  Yes, there is less metadata but I need that missing metadata so leaving it out is counter-productive.

For what?

My point is that the datatracker page is great for a standards jockey.
The tools page was better for an implementer or a student.

Both have their place (and it is good they link to each other!), but I’d argue the landing page should be more like the latter.
(Maybe there should be a cookie to cause auto-forwarding for the standards jockeys?)

> Also, from https://datatracker.ietf.org/doc/<i-d name> I get what is to me a clear display of the document history from which I can navigate to (almost) any earlier version.  I am puzzled that there should be any difficulty in clicking on the green or purple bar to select a different version (except when the submissions window is closing and authors submit three versions in under 24 hours and the bars shrink to zero).

Yes, that visualization is not bad if you need that information.
If you don’t, it is a waste of space.

> I think that the datatracker took a giant leap forward at some point from being unusable to being the best way into the work of the IETF so my home page became Active WGs. I often want to return there so that having the nav bar is most useful.

No contest on the opinion that the datatracker is awesome!
It really shows what situated software can evolve into.
But the point of situated software is that it is always optimized for a specific group of users, and I’m arguing there are two distinct groups here.

Grüße, Carsten

---

From: Robert Sparks <[email-masked]>
Date: Tue, 23 Feb 2021 09:42:00 -0600

On 2/23/21 6:16 AM, tom petch wrote:
> Also, from https://datatracker.ietf.org/doc/<i-d name>
To  be clear, that page is not going away.
> I get what is to me a clear display of the document history from which 
> I can navigate to (almost) any earlier version.  I am puzzled that 
> there should be any difficulty in clicking on the green or purple bar 
> to select a different version (except when the submissions window is 
> closing and authors submit three versions in under 24 hours and the 
> bars shrink to zero).
>

---

From: John C Klensin <[email-masked]>
Date: Tue, 23 Feb 2021 12:15:35 -0500

Tom,

Let me distinguish between two types of use contexts:

(1) Trying to find relevant I-Ds, working with I-Ds, trying to
build new documents, and so on.  While there are design issues
and matters of taste we could quibble about and debate endlessly
(the issue of whether the home page for an I-D should show a
page or two or the current /latest version or the whole thing is
probably a good example).  For me, apparently like you, the
current datatracker setup is entirely satisfactory for that
purpose.   Moreover, even about those matters of taste that were
decided in a way that does not match my preferences, I worry a
bit about improvements because I'm used to doing things the way
they are now and making things better might me extra work to
readjust those habits.   There are also things that I think
would make it lots better.  For example, I wish the IESG would
strongly encourage a "Changes since the last version" appendix
and that the datatracker would pick that information up and show
the subsection for the most recent version on that first page --
far more useful than the complete document, which is only a
click away in any of several formats.

(2) References from RFCs.  These need to be, at least by
default, exact.  The flexibilities that are an advantage with
the above can be a liability here.  Why? Because it is not
unusual for the substantive content of an I-D to change as work
evolves and consensus emerges (or doesn't).  If, for example,
version NN of an I-D said "the outside of the bikeshed MUST be
painted blue", version NN+1 said "the outside of the bikeshed
MUST be painted lime green" and explained why, it would be very
important if an RFC that referenced it for color choices point
to the version the RFC's author intended and not some other
version.  Would it be important for the reader to find out that
there is a later version in which things might have changed?
Sometimes, but only the document author is likely to know.

best,
   john

--On Tuesday, February 23, 2021 12:16 +0000 tom petch
<[email-masked]> wrote:

>>>> I am having trouble completely picturing just what you have
>>>> in mind, but, whatever you do, please keep in mind that
>>>> draft-foo-bar-baz-03 at the time of RFC publication,
>>>> wherever the link points should produce
>>>> draft-foo-bar-baz-03 and not its most recent successor,
>>>> whether that is
>>> Yes, but the landing page for -03 could have pointers to
>>> newer versions (I-D, RFC, Obsoleting RFC, …).
>> 
>> multiversion page that shows the most recent one and then has
>> to figure out how to navigate back to a particular version.
> 
> For me, the datatracker page that I get to from a datatracker
> WG page has the metadata that I need to work, whereas the
> tools page is sadly lacking in that regard.  Yes, there is
> less metadata but I need that missing metadata so leaving it
> out is counter-productive.
> 
> Also, from https://datatracker.ietf.org/doc/<i-d name> I get
> what is to me a clear display of the document history from
> which I can navigate to (almost) any earlier version.  I am
> puzzled that there should be any difficulty in clicking on the
> green or purple bar to select a different version (except when
> the submissions window is closing and authors submit three
> versions in under 24 hours and the bars shrink to zero).
> 
> I think that the datatracker took a giant leap forward at some
> point from being unusable to being the best way into the work
> of the IETF so my home page became Active WGs. I often want to
> return there so that having the nav bar is most useful.
> 
> Tom Petch
> 
>>>> This is, of course a
>> I probably missed how to do that in I-Ds referencing I-Ds
>> after I got frustrated many years ago with automated handling
>> of them and just started typing them in.
>>

---

From: Christian Huitema <[email-masked]>
Date: Tue, 23 Feb 2021 22:14:21 -0800

> Sometimes, but only the document author is likely to know.

Or, take the example of an Internet draft that ends up abandoned. 
References to such drafts are not rare. Now, what is also not rare is 
for the author of the abandoned draft to come back and "tombstone" it. 
You certainly don't want the reference to magically be updated and point 
to the tombstone.

-- Christian Huitema

---

From: John C Klensin <[email-masked]>
Date: Wed, 24 Feb 2021 02:21:37 -0500

--On Tuesday, February 23, 2021 22:14 -0800 Christian Huitema
<[email-masked]> wrote:

>> unusual for the substantive content of an I-D to change as
>> work evolves and consensus emerges (or doesn't).  If, for
>> example, version NN of an I-D said "the outside of the
>> bikeshed MUST be painted blue", version NN+1 said "the
>> outside of the bikeshed MUST be painted lime green" and
>> explained why, it would be very important if an RFC that
>> referenced it for color choices point to the version the
>> RFC's author intended and not some other version.  Would it
>> be important for the reader to find out that there is a later
>> version in which things might have changed? Sometimes, but
>> only the document author is likely to know.
> 
> Or, take the example of an Internet draft that ends up
> abandoned. References to such drafts are not rare. Now, what
> is also not rare is for the author of the abandoned draft to
> come back and "tombstone" it. You certainly don't want the
> reference to magically be updated and point to the tombstone.

Indeed.
    john

---

From: tom petch <[email-masked]>
Date: Wed, 24 Feb 2021 10:12:55 +0000

> Sometimes, but only the document author is likely to know.

John,

I agree - references must be exact and must be preserved ad inf.  I had 
not picked up a suggestion, starting with Julian's original post, that 
this was not the case, or about not to be the case.  Both the styles of 
reference he quotes have the version and date. And if I go to tools, 
then the link takes me to the relevant version.

I agree absolutely about the value of a 'Changes' section.  There is a 
200pp I-D teas-yang-te which provides a framework for other routing I-D 
to update, typically as 100 or so free-standing updates, although most 
individual updates conform a small number of templates.  (As one AD 
commented, if teas-te were different, it would save a lot of work - I 
suspect that the authors of teas-yang-te did not look ahead at the 
consequences of their chosen structure).  But more, teas-yang-te has 
undergone several revolutions rendering all updating I-D invalid; one 
such came in at revision 23, so any reference to -22 or earlier will be 
technically valid but tells me that the referring I-D is useless.  -26 
has just been announced, no 'Changes', no email about differences, no 
response to my e-mail asking what is different.  Sigh. (-25 did contain 
a technical flaw that passed unnoticed for many years and made it 
unusable and that has been fixed)

Oddly, on tools v datatracker, tools tells me that teas-yang-rsvp-te is 
up to -08 and references teas-te-22 ie is useless, while datatracker 
tells me that teas-yang-rsvp-te is up to -09 and references 
teas-yang-te-25 ie may or may not be useless depending on what is in -26.

And some wonder why I like datatracker!

Tom Petch

> .