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

Julian Reschke julian.reschke at gmx.de
Fri Mar 14 04:09:38 PDT 2014


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

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

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?

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


       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.

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

    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/?

    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:"?)

    The use of URLs in references is acceptable as long as the URL is the

s/URL/URI/

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

    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.

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

Define "dated".

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

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.

    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.


    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?

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

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.

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.

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

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

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

Best regards, Julian


More information about the rfc-interest mailing list