[rfc-i] comments on RFC style guide draft

Heather Flanagan (RFC Series Editor) rse at rfc-editor.org
Mon Jul 29 01:09:53 PDT 2013


Thank you for your comments, Wes.  I will be reviewing these and other
comments over the next few weeks.

-Heather Flanagan

On 7/19/13 8:33 PM, George, Wes wrote:
>
> 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.
>
>  
>
> Thanks,
>
>  
>
> Wes George
>
>  
>
> *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]."
>
>  
>
> Thanks,
>
>  
>
> Wes George
>
> 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...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20130729/08c12436/attachment-0001.htm>


More information about the rfc-interest mailing list