[rfc-i] feedback on draft-iab-styleguide-01

Julian Reschke julian.reschke at gmx.de
Mon Mar 24 11:17:25 PDT 2014


On 2014-03-24 18:55, Heather Flanagan (RFC Series Editor) wrote:
> ...
>>>>      The following format is required when a reference to an errata
>>>> report
>>>>      is necessary:
>>>>
>>>>         [ErrNNNN]  RFC Errata, Errata ID NNNN, RFC NNNN,
>>>>                    <http:/www.rfc-editor.org>.
>>>>
>>>>         [Err1912]  RFC Errata, Errata ID 1912, RFC 2978,
>>>>                    <http://www.rfc-editor.org>.
>>>>
>>>> Big -1. The RFC Editor should provide stable URIs for errata, and they
>>>> should be used in the reference.
>>>>
>>>> Also, the format is very misleading. The erratum is not the RFC, so
>>>> this
>>>> is a case where the notation deviates from what we use elsewhere.
>>>>
>>>> Can we make it "RFC Erratum RFCXXXX-NNNN", so we can drop the "RFC
>>>> NNNN"
>>>> entry?
>>>
>>> The errata system is slated for a pretty extensive overhaul as part of
>>> the fallout from the upcoming format changes.  I suggest leaving the
>>> Style Guide guidance as is for now, noting that it will change
>>> significantly in the next 12-24 months.
>>
>> -1. This is new text. Either don't have it at all, or get it right now.
>
> I argue that the new text is, while not a complete answer to what we
> need to do with errata, is still an improvement over what we have today.

I believe the first point I made needs to be addressed:

"Also, the format is very misleading. The erratum is not the RFC, so 
this is a case where the notation deviates from what we use elsewhere."

Also, why can't we define the stable errata URI right now?

> ...
>> Also, I don't think pointing readers at the info page does them a
>> favor right now, as the thing they likely want to see is the actual
>> document, not the metadata about it.
>
> Sandy and I talked about this, and felt that the info page was the best
> choice for two main reasons:
> - in the future, we will have multiple publication formats and people
> will need to be sent to a location where they can choose the one they want

People following a link on the web will want to see the HTML version 
something like 99.9% of the time.

That being said, we need to discuss how to reach the goal of having 
search engines return meaningful results of RFC searches. If we insist 
on linking only to the metadata, the *actual* spec will not get the 
ranking it should have.

> - this is the best way to make sure readers know that errata and IPR are
> associated with an RFC; that's not something one can see in the current
> canonical format.

RFCs already carry the link to the info page in the front matter, no?

>>>>      [FYI90]    Malkin, G. and J. Reynolds, "FYI on FYI: Introduction to
>>>>                 the FYI Notes", FYI Notes, RFC 1150, March 1990.
>>>>
>>>>                 Housley, R., "Conclusion of FYI RFC Sub-Series", RFC
>>>> 6360,
>>>>                 August 2011.
>>>>
>>>>                 <http://www.rfc-editor.org/info/fyi90>
>>>>
>>>> Another format xml2rfc can't easily produce...
>>>
>>> Yes, but the code can change and the editors can add the URI when
>>> necessary.
>>
>> The point being: if the style guide requires a format that xml2rfc
>> currently can't generate then you ought to bring that up as a feature
>> request.
>
> I think you and I are mostly disagreeing on what comes first - the Style
> Guide or the changes in code.  Is that an accurate statement?

I believe it should happen in parallel.

A style guide that requires things the tools don't do results either in 
documents being published that do not follow the guide, or the 
production center having to do additional manual work, which 
occasionally may lead to unnecessary mistakes.

Best regards, Julian


More information about the rfc-interest mailing list