[apps-discuss] On citations in general

[Barry Leiba <[e-mail]>]

While I'm on the topic of citations, let me throw something out to
this crowd before sending it to the general IETF discussion list.

There are various styles of using citations, and various strongly held
opinions about which ones are good, which evil, and which lie
somewhere between.  I don't want to make this a religious argument,
though I'm pretty sure it will be that, but here:

I consider that a citation in the text serves two purposes.  One is to
explain where the information came from, and the other is to make it
easy to get to the cited document.  As cute as it may be to say things
like, "To use items defined in [EMAIL], one must additionally...", I
find that it's not very helpful when I reading documents.

What I prefer to see -- what helps me the most as a reader -- is both
short text and an RFC number.  Often, if the short text is properly
chosen, I don't have to look at the referenced document at all.  And
when I do, I can find it immediately from the RFC number in the
citation, without having to bounce to the bottom of the doc and look
at the references.  Of course, if there are repeated citations, I
don't expect every one to have the full thing, and just the RFC
citation is enough.

Here's the sort of thing I'm talking about (made-up examples, mostly):

"...is done through SMTP [RFC5321]..."
"...SHOULD be signed using DKIM [RFC6376]..."
"The script can use the External-lists extension [RFC6134] to..."
"If a DNS block list [RFC5782] includes an IP address..."

It's also sometimes very useful to have section numbers in the
citations, when one needs to be referred to a specific point in the
cited document.  Consider this, from one of the httpbis documents:

"The field value consists of a single URI-reference.  When it has the
form of a relative reference ([RFC3986], Section 4.2), the final value
is computed by resolving it against the effective request URI
([RFC3986], Section 5)."

I find all of these to be MUCH more useful to the reader than, say,
"The script can use [RFC6134] to...", or, "If a [DNSBL] includes an IP
address...", even though the full information is in the References
section in any case.

Comments?

Barry