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

Heather Flanagan (RFC Series Editor) rse at rfc-editor.org
Mon Mar 24 09:33:31 PDT 2014


On 3/14/14, 4:09 AM, Julian Reschke wrote:
>    Guidance provided by this document will not be applied until
>    published as an RFC.  Please send your comments about the contents of
>    this document to <rfc-interest at rfc-editor.org>.
> 
> The last sentence shouldn't be part of the abstract (but an Editorial
> Note).

It won't be part of the document at all, when published.

> 
>    *  When a sentence ended by a period is immediately followed by
>       another sentence, there should be two blank spaces after the
>       period.
> 
> This is a rule that (IMHO) only makes sense for plain text renderings.
> It requires heuristics in the generator tools to detect line ends. We
> really should get rid of it.

Its utility largely depends on the fonts used.  I don't know of any font
where two spaces versus one after a period causes difficulty in reading,
whereas with some fonts it is helpful.  If it does no harm, and some
good, I would rather keep this rule.

> 
> 3.5.  Abbreviation Rules
> 
>    Abbreviations must be expanded in document titles and upon first use
>    in the body of the document, which includes the Abstract.  The full
>    expansion of the text should be followed by the abbreviation itself
>    in parentheses.   The exception is abbreviations that are so common
>    that the readership of RFCs can be expected to recognize them
>    immediately; examples include (but are not limited to) TCP, IP, SNMP,
>    and FTP.  The online list of abbreviations [ABBR] provides guidance.
> 
> Can we replace "FTP" by "HTTP" please?

Sure.

> 
>       Note: The online list of abbreviations is not exhaustive or
>       definitive.  It is a list of abbreviations appearing in RFCs and
>       sometimes reflects discussions with authors, WG chairs, and/or
>       ADs.  Note that some abbreviations have multiple expansions.
> 
> ADs -> "Area Directors (ADs)"
> 
> Fun aside, it would be cool if this document would follow the rules it
> describes...

Valid point.

> 
> 
>       First-page header                      * [Required]
>       Title                                    [Required]
>       Abstract                                 [Required]
>       RFC Editor or Stream Manager Note      * [Upon request]
>       Status of this Memo                    * [Required]
>       Copyright and License Notice           * [Required]
>       Table of Contents                        [Required]
>       Body of the Memo                         [Required]
>         1.  Introduction                       [Required]
>         2.  Requirement Words (RFC 2119)
>         3.  ...
>             MAIN BODY OF THE TEXT
>         6.  ...
>         7.  IANA Considerations                [Required in I-D]
>         8.  Internationalization Considerations
>         9.  Security Considerations            [Required]
>         10.  References
>         10.1.  Normative References
>         10.2.  Informative References
>         Appendix A.
>         Appendix B.
>       Acknowledgments
>       Contributors
>       Author's Address                         [Required]
> 
> "Acknowledgements" and "Contributors" are usually just a section (not
> appendix), because that's the only form xml2rfc can generate. We should
> align the tools with the style guide or vice versa.

Yes.  Some of the guidance in the new Style Guide will require changes
in the tools in order to fully implement.

> 
>    The elements preceding the body of the memo should not be numbered.
>    Typically, the body of the memo will have numbered sections and the
>    appendices will be labeled with letters. Any sections that appear
>    after the appendices should not be numbered or labeled (e.g., see
>    "Contributors" above).
> 
> (see above)
> 
>    If an author cannot or will not provide an affiliation for any
>    reason, "Independent", "Retired", or some other term that
>    appropriately describes the author's affiliation may be used.
>    Alternatively, a blank line may be included in the document header
>    when no affiliation is provided.
> 
> I believe that's new, and the xml2rfc processors may not support that yet.
> 
>    To simply specify a necessary logical relationship, the normal
>    lowercase words should be used.  On the other hand, if the
>    capitalized words are used in a document, choose and use them
>    carefully and consistently.
> 
> This seems to contradict advice from BCP14: "These words are often
> capitalized." Note: "often", not "always".

If an author referred to RFC 2119 and yet did not use capitalized words,
the RFC Editor would definitely question and push back.  RFC 2119
language without that subtle clue of ALL CAPS would not fit under the
guiding principles of readability, clarity, consistency, and uniformity.

> 
>    All RFCs that deal with internationalization issues should have a
>    section describing those issues; see "IETF Policy on Character Sets
>    and Languages" [BCP18], section 6, for more information.
> 
> s/section/Section/?

ack

> 
>    A reference to an RFC that has been assigned an STD [RFC1311], BCP
>    [RFC1818], or FYI [FYI90] sub-series number must include the sub-
>    series number of the document.  Note: the FYI series was ended by RFC
>    6360.  RFCs that were published with an FYI sub-series number and
>    still maintain the FYI number must include the sub-series number in
>    the reference.
> 
> (insert paragraph break before "Note:"?)

I think there was a reason we had that within a single paragraph, but
I'll check with Sandy.

> 
>    The use of URLs in references is acceptable as long as the URL is the
> 
> s/URL/URI/

ack

> 
> Also, doesn't this need to be expanded? :-)

No.  It's on the abbreviations list.

> 
>    most stable (i.e., unlikely to change and expected to be continuously
>    available) and direct reference possible.  The URL will be verified
>    as valid during the RFC editorial process.  Personal web pages and
>    web caching services are not considered stable and will not be
>    accepted as a normative reference.  Informative references to blogs
>    are acceptable if they are an organizational blog and not a personal
>    space.
> 
> I believe this is hard to check. I also note that personal spaces
> frequently are much more stable than corporate web pages.

I think this is the weakest section of the RFC.  On the one hand, both
authors and editors need some guidance on judging a stable reference.
On the other hand, there is no such thing as truly "stable" when we're
talking about web references.  The technical publishing industry as a
whole finds this challenging.

So, yes, this is hard to check.  I am still researching a better way to
deal with this issue.

> 
>    If a dated URL is available for a referenced web page, its use is
>    required.
> 
> Define "dated".

dat·ed
adjective

1:  provided with a date <a dated document>

> 
>       [RFCXXXX] Last name, First initial., "RFC Title",
>                 BCP/FYI/STD ## (if applicable), RFC ####,
>                 Date of Publication.
> 
> Why do we have the restriction to "first initial"?
> 
> 
>    References to Internet-Drafts can only appear as Informative
>    references. Given that several revisions of an I-D may be produced in
>    a short time frame, references must include the publication date
>    (month and year), the full Internet-Draft file name (including the
>    version number), and the use the phrase "Work in Progress".  If the
> 
> I note that Paul's draft currently is in conflict with this rule... Yes,
> it's only an Internet Draft, but still it would be good to discuss the
> use of unversioned ID references.

Most of the guidance around referencing I-D has been revised in this new
Style Guide.  I wouldn't expect current drafts to have applied this
guidance.

> 
> WRT to "Work in Progress" - this has been discussed a lot, including in
> an RSE-appointed team, and the outcome was that this needs to be
> relaxed, as "Work in Progress" is totally misleading for historic drafts.

Yes, but changing it means that RFC 2026 itself has to be updated, and
that can't be done with an Informational RFC like the Style Guide.  We
should tackle that as a separate issue.

> 
>    I-D referenced has a version published as an RFC, references must
>    also include the RFC.
> 
> Sentence incomplete. Example helpful. May be something that needs
> xml2rfc extensions.

Fixed.

> 
> 
>    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.

> 
>       [W3C.REC-xml11]
>               Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
>               Yergeau, F., and J. Cowan, "Extensible Markup Language
>               (XML) 1.1 (Second Edition)", W3C Recommendation
>               REC-xml11-20060816, August 2006, <http://www.w3.org/TR/
>               2006/REC-xml11-20060816>.
> 
> The format recommended by the W3C is different. See
> <http://greenbytes.de/tech/webdav/rfc2629xslt/w3c-references.html>.

I'll discuss this with Sandy and Alice.

> 
> 4.9.  Appendices
> 
>    The RFC Editor recommends placing references before the Appendices.
>    Appendices should be labeled as "Appendix A.  Appendix A Title",
>    "A.1.  Appendix A.1 Title", "Appendix B.  Appendix B Title", etc.
> 
> That reads weird, maybe use a different string for the title.

I've chanced it to "Appendices Section"

> 
> 4.11.  Contributors Section
> 
>    This optional section acknowledges those who have made significant
>    contributions to the document.
> 
>    In a similar fashion to the Author section, the RFC Editor does not
>    make the determination as to who should be listed as a contributor to
>    an RFC.  The determination of who should be listed as a contributor
>    on an RFC is determined by stream policy.
> 
>    The Contributors section may include brief statements about the
>    nature of particular contributions ("Sam contributed Section 3"), and
>    it may also include affiliations of listed contributors.  At the
>    discretion of the author(s), contact addresses may also be included
>    in the Contributors section, for those contributors whose knowledge
>    makes them useful future contacts for information about the RFC.  Any
>    contact information should be formatted similar to how the
>    information is formatted in the Author's Address section.
> 
> We need to extend the v3 vocab to deal with this.

OK

> 
>    [BCP14]    Bradner, S., "Key words for use in RFCs to Indicate
>               Requirement Levels", BCP 14, RFC 2119, March 1997,
>               <http://www.rfc-editor.org/info/bcp14>.
> 
> Why is there a URI in here?

Where we do have known, stable URIs, such as for RFCs and associated
subseries, we are including the URI in the reference.

> 
>    [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.

> 
>    [ISO3297]  Technical Committee ISO/TC 46, Information and
>               documentation, Subcommittee SC 9, Identification and
>               description, "Information and documentation -
>               International standard serial number (ISSN)", 09 2007.
> s/09/September/?
> 
>    [RFC1818]  Postel, J., Li, T., and Y. Rekhter, "Best Current
>               Practices", RFC 1818, August 1995,
>               <http://www.rfc-editor.org/info/rfc1818>.
> 
> Why is there a URI in here?

See above.

Thank you for reviewing the draft!

Heather



More information about the rfc-interest mailing list