Should every RFC reference be linked?

Hi,

In our doc, there are plenty of references to the RFC statements. Some of them are wrapped with sphinx’s RFC label (:rfc:`XXXX`) which links to a RFC website and some of them are not(RFC XXXX).

Should we standardize all RFC statements with adding a link?

A typical instance of this is in the doc of http.cookiejar, where 2/3 RFC references are linked, and others are not. This occurs in many other docs.

I am +1 on attaching all references with a link, as most of it does.

1 Like

I don’t think repeated references (at least when there’s good locality) need to be linked. Which is how the example you mention is written - within a given paragraph or short section, only the first reference is linked. It makes the text a bit less “noisy”.

6 Likes

See also the style guide:

Links are a powerful tool for helping people navigate documentation and find more information, but links can be over-used. Links should be used only if they help the reader.

Generally, a link should be provided for the first use of a term in a unit, such as a section or paragraph. This is not a hard and fast rule. Sometimes the second mention is more appropriate for a link. Some units are long enough to have a few repeated links. Use judgement to decide when a link will help the reader.

4 Likes