[rfc-i] comments on RFC style guide draft
Heather Flanagan (RFC Series Editor)
rse at rfc-editor.org
Wed Jan 22 17:27:56 PST 2014
Thank you, Wes. I have asked the RSOC to consider supporting the -03
version of this I-D as one that the IAB should consider accepting as an
IAB stream document. From there, it would follow the publication
process for an IAB doc, described in RFC 4845, which includes a full
community comment period. I haven't been trying to sneak drafts in
behind the scenes. :-)
That said, some comments below:
On 1/22/14 2:29 PM, George, Wes wrote:
> Reviewed the latest version –03. It addresses some of my concerns,
> others are still outstanding from previous reviews and listed below with
> updated section numbers where appropriate, awaiting response.
> 4.8 should include a reference/requirement to use RFC5737 and 3849
> documentation prefixes whenever IP addresses are used in examples unless
> use of a different range is specifically justified/required.
I am not opposed to this, but I would like to get more community input
as to whether that kind of information should be included or whether it
is stream specific.
> 220.127.116.11: Certainly the need for stability in citations for scholarly
> work isn’t unique to IETF. Is there any guidance on citation of URIs in
> published materials within MLA/APA CMOS or academic journal editorial
> guidelines that addresses this need for stability in archival documents?
> If such a thing exists, I’d rather we use that guidance as a baseline
> and then discuss exceptions rather than building our own.
That is very true, this isn't a unique problem. Unfortunately, there is
little in the way of standard guidance on how to handle this. The CMOS
itself, the primary style guide followed by the RFC Editor, does not
provide sufficient guidance. Section 14.4 suggests using URIs, but
section 2.31 says "authors should consider not including any URLs that
seem potentially unstable or subject to change." As you point out
below, stability is a difficult to define concept.
> As to the current text:
> The criteria for determining whether a page is a “personal web page” and
> therefore unacceptable as a citation must be clearly defined, or this
> restriction should be eliminated. The RSE is not equipped to determine
> which websites are stable and which are not based on a spot evaluation
> at the time of publishing, and it’ll just lead to unproductive arguments
> with authors if it’s “I’ll know it when I see it."
I understand your point, but I have to disagree about removing room for
interpretation by the editors. Judgement calls are a regular part of
what we do, and I want to find a balance between reasonable guidance and
rigid prescription during those judgement opportunities.
> Additionally, this notion of stable URL references is a bit of a pipe
> dream. Even the most stable of websites undergo reorganizations, and
> only the sites that take great care not to break their existing link
> structure or ensure that redirection works properly or leave a tombstone
> will have truly stable references. In the cases where the URL goes 404,
> sometimes a simple web search based on the bibliographical reference
> information will net a result, other times not. Then there’s the matter
> of things like Wikis (esp Wikipedia) where the URL may remain constant
> but the content the author intended to have seen by a reader following
> the reference could well have been edited out or changed such that it
> alters the usefulness of the reference to the document. I can
> understand explicitly prohibiting the use of url shorteners, since that
> virtually guarantees a broken link within a few months, but beyond that,
> the only thing the RSE can do is make a best effort to ensure that the
> site is functional at publishing time. If you want to ensure
> archival-quality URL stability, it’s probably going to require allowing
> errata to correct/update dead links, or the use of a static web archive
> for URL references based on the time of the document’s publishing.
Actually, I think there is going to be a solution for this, being
developed in academia. Some discussion with other academic and
technical publishers suggest libraries are looking into the problem of
stablizing references in today's world of ephemeral content. I hope to
have more on that in the next few months.
> And if the RSE’s policy is to prohibit the use of the Internet Archive
> (Wayback Machine) as a stable cited reference, that needs to be
> specifically documented and justified in this section of the style
> guide, especially to explain why this is not considered a stable source
> when its sole purpose is archival. I think that’s what you intended with
> the addition of “web caching services” to your prohibited URI citations,
> but I think that you’re miscategorizing archive.org by lumping it in as
> a caching service. https://archive.org/about/
> Section 4.12: Since people often change employers, service providers,
> etc multiple times during the life of an archival document’s relevance,
> sometimes due to circumstances beyond the author’s control, the use of
> long-lived email addresses is a nice idea at best. The RSE needs to
> consider some alternatives here to assist with maintaining contact with
> document authors despite the fact that both physical and email addresses
> are subject to change.
I have tried to think of ways that the RFC Editor could more effective
identify and track authors that would not in turn impact our role of
editor, publisher, and archivist. Based on experiences in other jobs,
identity management is not a small task. Our current process, to accept
changes to contact information and adjust our information internally, is
not ideal, but I am at a loss for a better way for that meets the needs
of the IETF community.
I point to the thread last September on the ietf at ietf.org mailing list
that discussed this problem in detail:
All that said, I think the guidance in the Style Guide itself is
reasonable; the issue of managing contact information is a different
> Alternatives that come to mind:
> -creating a permanent email alias such as RFCnnnn at tools.ietf.org
> <mailto:RFCnnnn at tools.ietf.org> that allows the authors to update the
> contact email address associated with them if and when it changes (this
> goes towards support of a metadata model for RFC format, I suppose).
I have several concerns about this approach - what about non-IETF
documents? How does this solve for authors who, for whatever reason, do
not keep up with their contact information. Still, perhaps something
could be suggested as a code sprint project. More thought is needed here.
> -allowing an erratum to be filed against the RFC to update author
> contact info (this preserves the archival nature of the document, while
> allowing for an important update to ensure that the author can be
> contacted for IPR matters, questions/comments, etc).
I'm not clear on what you mean - allow the author to submit an errata
when their address changes, or allow a reader to submit an errata when
they cannot reach the author?
If an author lets us know that their address has changed, we make a
change in a database. Any errata then submitted are emailed to that
address, not what's in the RFC. This is a manual process on our part,
though, and we need better tools to support this effort.
> Also, an official style guide should probably eliminate the
> colloquialism “munged addresses” since it adequately explains what it
> means by that phrase such that the phrase itself is no longer necessary.
I have no objection to removing that phrase.
More information about the rfc-interest