Subject: [rfc-i] Citing drafts

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Feb 2021 08:35:11 +0100

Hi there.

Looking at <https://www.rfc-editor.org/styleguide/part2/> I found:

> Referencing Internet-Drafts 	References to Internet-Drafts will list the series as Internet-Draft, will include the day of publication for the version referenced, and will include a URL to the HTML file (with no file extension). For example:
>
> [RFC7322bis]
>        Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in
>        Progress, Internet-Draft, draft-flanagan-7322bis-03,
>        3 April 2018, <https://tools.ietf.org/html/draft-flanagan-7322bis-03>.

Looking at
<https://tools.ietf.org/html/draft-flanagan-7322bis-06#section-4.8.6.3>:

>    [SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) and
>    First initial.  Last name, Ed. (if applicable), "I-D Title", Work in
>    Progress, Internet-Draft, draft-string-NN, Day Month Year.
>
>    Example:
>
>    [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide", Work in
>    Progress, Internet-Draft, draft-flanagan-style-04, 27 September 2019.

Note that the recommendations are inconsistent, and that the first one
(from the web site) adds a link to tools.ietf.org.

(I'll also note that inserting a comma between "Internet-Draft" and the
draft name is yet another "special case" for IETF documents which does
not seem to have a good reason).

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

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 22 Feb 2021 09:15:10 +0100

> (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.)

We used to use the tools.ietf.org page as a landing page for citing RFCs as well (or the equivalent in https://www.rfc-editor.org/rfc/rfc7049.html).
We now have https://www.rfc-editor.org/info/rfc8949, which is a landing page, but less useful as it doesn’t have the content.
(And it still has a link to one PDF software vendor :eyeroll:.)
https://www.rfc-editor.org/rfc/rfc8949 uses metadata.js to turn the original HTML into a basic, but useful landing page as well.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Feb 2021 09:35:08 +0100

> People like that page a lot because it has the relevant metadata and links as well as the content of the draft.

Understood. I'm only surprised that the RFC Style Guide now essentially
*mandates* this - my understanding is that we're trying to replicate all
"essential" services that are currently on tools.ietf.org to an official
place on ietf.org.

> https://www.rfc-editor.org/rfc/rfc8949 uses metadata.js to turn the original HTML into a basic, but useful landing page as well.

FWIW, I totally agree that the "canonical" links for RFCs and IDs should
take people to a page that doesn't require following another link to the
actual content.

Right now my concern however is that the RFC Style Guide seems to
require something that is inconsistent with other recommendations.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 22 Feb 2021 09:36:39 +0100

> require something that is inconsistent with other recommendations.

(And I’m trying to use the energy from the desire to fix this inconsistency to make the result useful as well :-)

Grüße, Carsten

---

From: Robert Sparks <[email-masked]>
Date: Mon, 22 Feb 2021 13:10:44 -0600

> (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 lan…

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.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 22 Feb 2021 20:13:40 +0100

On 2021-02-22, at 20:10, Robert Sparks <[email-masked]> wrote:
> 
> 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.

Beautiful!

If we find a way to shorten the “doc/html” part of the URI some more, this would not hurt.

Grüße, Carsten

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 23 Feb 2021 06:58:44 +1100

> Beautiful!

Yes, thanks Robert. I already prefer that page, but improvements are most welcome.

> If we find a way to shorten the “doc/html” part of the URI some more, 

That is what bothers you? For me it is the string "datatracker".

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 22 Feb 2021 21:01:18 +0100

> That is what bothers you? For me it is the string "datatracker".

But that already has an abbreviation: dt.ietf.org

Maybe doc.ietf.org/rfc8949 is the right URI?

Grüße, Carsten

---

From: tom petch <[email-masked]>
Date: Fri, 26 Feb 2021 17:28:25 +0000

On 22/02/2021 19:10, Robert Sparks wrote:
>> 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.)
>

My pet hate is that I have to scroll to the bottom before I can tell the 
system that I want the lot.

I always judge customer-facing web, e.g. for finding goods, purchasing 
goods, by whether or not the button I need is on the screen, or whether 
I have to page all the way up only to find I have to page all the way 
down and maybe scroll left and right as well in order to get to the 
button that is essential to progress.

It is amazing how many businesses impose this once I have decided that I 
want to checkout and make a purchase!

Tom Petch

>> We used to use the tools.ietf.org page as a landing page for citing
>> RFCs as well (or the equivalent in
>> https://www.rfc-editor.org/rfc/rfc7049.html).
>> We now have https://www.rfc-editor.org/info/rfc8949, which is a
>> landing page, but less useful as it doesn’t have the content.
>> https://www.rfc-editor.org/rfc/rfc8949 uses metadata.js to turn the
>> original HTML into a basic, but useful landing page as well.
>
>>
>> Grüße, Carsten
>>