[rfc-i] comments on RFC style guide draft
wesley.george at twcable.com
Fri Jul 19 11:33:56 PDT 2013
I've finally gotten around to reviewing the latest version of the style guide. Most of my comments from reviewing a prior version (below) have not been addressed, but it appears that my original message may have gotten stuck in the subscription problems that I had when I originally subscribed to RFC-interest, so I'm resending to get them on-list for discussion.
I'll note that the subject of my original comments regarding section 3.2 and the number of spaces after periods came up in a previous thread, but in the context of tools parsing text, rather than the external style. http://www.rfc-editor.org/pipermail/rfc-interest/2013-April/005532.html (and subsequent messages). My citations on the standard (http://www.rfc-editor.org/pipermail/rfc-interest/2013-April/005534.html) were "debunked" by a long post on the history (http://www.rfc-editor.org/pipermail/rfc-interest/2013-April/005540.html), but I think that sort of misses the point I was trying to make - both are accepted standards, and we'll have no better luck declaring one "right" and the other "wrong" than were we to do that with British vs American English. My original comments (less the parts quoted in the threads above) are below.
From: George, Wes
Sent: Friday, November 02, 2012 5:39 PM
To: rfc-interest at rfc-editor.org; 'draft-flanagan-style at tools.ietf.org'
Subject: comments on RFC style guide draft
I've reviewed draft-flanagan-style-00<http://tools.ietf.org/html/draft-flanagan-style-00> and I have comments.
First a general formatting comment - some additional sections to break up the content in section 4.8 would be very helpful for readability and citation. The bulleted items make up significant subsections, rather than a simple bulleted list.
4.8 Requirement words (RFC 2119) may want to reference draft-hansen-nonkeywords-non2119 assuming that draft goes forward, or perhaps even incorporate some of the text of that draft directly into the style guide.
4.8 should likely also include a specific 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.
Regarding section 4.9: 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.
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).
-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).
Regarding munged addresses - if you assert that this doesn't help to reduce spam, and represents an unacceptable barrier for human readers, you need a citation supporting such. I'm not saying you're wrong, just that a citation would help. Also, IETF is inconsistent in their use of munged addresses on official web pages that list contact info for I* members and WG chairs. If munging in fact doesn't help and is simply annoying, we need to stop doing it everywhere. 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.
Finally, the guidance on the use of URLs as references in RFCs in section 4.8 subsection "References" is a little thin right now. Is there any guidance on citation of URLs in published materials within MLA/APA or other style guides 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.
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 personal websites are stable and which are not based on a spot evaluation at the time of publishing, outside of perhaps identifying a site that is hosted on ISP-provided space that will go away if the owner ever cancels service with that provider.
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.
And to go back to a related argument from some months ago, if the RSE's policy is to prohibit the use of the Internet Archive (Wayback Machine) as a cited reference, that needs to be specifically documented and justified in the style guide. Since I ran afoul of this personally in a draft I was working on, I'll reprise a bit of the discussion I had with Ms. Flanagan at the time because I think it is relevant in this case. I'm not trying to rehash the argument with Ms. Flanagan, but instead to add some points to the discussion as this group works towards consensus on this issue, assuming that consensus is indeed the goal.
"> I understand the rationale behind trying to avoid ephemeral references
> in a "permanent" document, but that seems to support
> *using* wayback machine URLs (e.g. "the most stable reference
> available"), rather than avoiding them, because it's more certain that
> this version will not have its content significantly altered from what
> the author intended to cite, and there is less risk of the site
> disappearing. The Wayback machine crawls and stores websites as
> date-based snapshots, and it never deletes a snapshot.
> It adds additional snapshots if the content changes. Currently, "web
> 2.0" sites are unlikely to fare well in the archive process because of
> the active content, but more standard text content is archived quite
> effectively. In other words, by citing a specific date version of a
> website on the Internet Archive, the author is ensuring that there is
> a snapshot of the site that is representative of the version available
> when the RFC is published, since RFCs are generally a snapshot of
> consensus and rationale at the time of their publishing.
> The use of web.archive.org for informative references in published RFCs is not without precedent (RFCs 4329 and 6265, and there are a number of other I-Ds, plus the IETF-hosted timezone data) and so I feel like there is a bit of a double-standard at work here, both for this draft and for the Web Archive site. When the RSE validates URLs in an I-D, my guess is that they go to the site and make sure that it loads. They don't make any judgments about the relevance of the content, whether the subtending links on the resulting page all work properly, or when the domain expires, etc. Yet that's exactly what you're saying is the problem with the web archive [that some parts of an archived page might not work]."
Anything below this line has been added by my company's mail server, I have no control over it.
This E-mail and any of its attachments may contain Time Warner Cable proprietary information, which is privileged, confidential, or subject to copyright belonging to Time Warner Cable. This E-mail is intended solely for the use of the individual or entity to which it is addressed. If you are not the intended recipient of this E-mail, you are hereby notified that any dissemination, distribution, copying, or action taken in relation to the contents of and attachments to this E-mail is strictly prohibited and may be unlawful. If you have received this E-mail in error, please notify the sender immediately and permanently delete the original and any copy of this E-mail and any printout.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the rfc-interest