[rfc-i] feedback on draft-iab-styleguide-01
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
* When a sentence ended by a period is immediately followed by
another sentence, there should be two blank spaces after the
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
First-page header * [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)
MAIN BODY OF THE TEXT
7. IANA Considerations [Required in I-D]
8. Internationalization Considerations
9. Security Considerations [Required]
10.1. Normative References
10.2. Informative References
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
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
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.
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
(insert paragraph break before "Note:"?)
The use of URLs in references is acceptable as long as the URL is the
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
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
[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
The following format is required when a reference to an errata report
[ErrNNNN] RFC Errata, Errata ID NNNN, RFC NNNN,
[Err1912] RFC Errata, Errata ID 1912, RFC 2978,
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"
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/
The format recommended by the W3C is different. See
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,
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,
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.
[RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current
Practices", RFC 1818, August 1995,
Why is there a URI in here?
Best regards, Julian
More information about the rfc-interest