Technical specifications produced by committees with multiple phases of editorial review and feedback are susceptible to myriad QA risks, clerical and otherwise.
The Internet Engineering Steering Group (IESG) has announced the publication of a technical memo which "defines a list of often called 'ID-NITS' that need to be checked before an Internet-Draft will be accepted for IESG consideration. The intent is that Working Group chairs check an I-D for any nits before submitting a request-for-publication. All Internet Drafts which are offered for publication as RFCs must conform to the stated requirements or they will be returned to the author(s)/editor(s) for revision."
Several items in the checklist related to ABNF and XML syntax used in formal definitions and examples. Additionally, as a suggestion for productivity improvement, the Checklist document strongly recommends following RFC 2629 (Writing I-Ds and RFCs using XML) in the creation of XML source files for generating an Internet Draft. There is an online xml2rfc tool to generate the nroff and Internet Draft files; this tool automatically takes care of most of the formatting, administrative and bureaucratic rules."
According to the new Checklist document, all incorporated ABNF grammars must be checked, and an online tool is available for validating IETF ABNFs. "Protocol specifications that use XML should always use well-formed XML at a minimum. Sample XML instances included in a specification have to be well-formed, and if the XML is supposed to be valid (according to the current W3C definition of validity), the samples must reference and be validated using an appropriate XML Schema, DTD, or other standard validation mechanism that is structurally and syntactically correct. XML provides structures, such as the <any> element information item in XML Schema, to allow element extensions. If these structures are included in a protocol, the protocol specification must include clear guidance on how, when, and where the extension structures, such as versioning, can be used. All XML Schemas, Namespaces, and Resource Description Framework (RDF) Schemas should be registered with the IANA using the procedures described in Best Current Practice 81, The IETF XML Registry."
The new IESG Checklist document is applicable to "finished" Internet Drafts submitted for publication, but the IESG recommends that the rules and guidelines be followed for any Working Group Last Call documents also. IETF Working Group Chairs are required to have the checks performed before submitting a specification to the Area Directors; the IETF Area Directors will not accept a document or put it on the IESG agenda if the checks have not been made. In the case of individual Internet Draft submissions, authors are responsible for checking documents against the QA rules.
Checklist for Internet-Drafts (IDs) Submitted for RFC Publication. Prepared by Bert Wijnen (Lucent Technologies), for the Internet Engineering Steering Group (IESG). Reference: ID-Checklist Revision 1.1. May 18, 2004 and later.
Related IETF Resources:
The IETF XML Registry. By Michael Mealling (VeriSign, Inc). IETF Network Working Group, Request for Comments: 3688. BCP: 81. Category: Best Current Practice. "This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. The document seeks to standardize and improve these practices by creating an IANA maintained registry of XML element identifiers so that document authors and implementors have a well maintained and authoritative location for their XML elements. As part of this standard, the IANA will maintain: (1) the public representation of the document; (2) the URI for the elements if one is provided at the time of registration; (3) a registry of Public Identifiers as URIs. In the case where the registrant does not request a particular URI, the IANA will assign it a Uniform Resource Name (URN) that follows RFC 3553..." [IETF source]
Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols. By Scott Hollenbeck (VeriSign, Inc), Marshall T. Rose (Dover Beach Consulting, Inc), and Larry Masinter (Adobe Systems Incorporated). IETF Request for Comments: 3470. BCP: 70. January 2003. "The Extensible Markup Language (XML) is a framework for structuring data. While it evolved from Standard Generalized Markup Language (SGML) — a markup language primarily focused on structuring documents — XML has evolved to be a widely-used mechanism for representing structured data. There are a wide variety of Internet protocols being developed; many have need for a representation for structured data relevant to their application. There has been much interest in the use of XML as a representation method. This document describes basic XML concepts, analyzes various alternatives in the use of XML, and provides guidelines for the use of XML within IETF standards-track protocols..."
Writing I-Ds and RFCs Using XML. By Marshall T. Rose (Invisible Worlds, Inc). IETF Request for Comments: 2629. "This memo presents a technique for using XML (Extensible Markup Language) as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series."
Augmented BNF for Syntax Specifications: ABNF. IETF Network Working Group. Request for Comments: 2234. "Internet technical specifications often need to define a format syntax and are free to employ whatever notation their authors deem useful. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. It balances compactness and simplicity, with reasonable representational power. In the early days of the Arpanet, each specification contained its own definition of ABNF. This included the email specifications, RFC733 and then RFC822 which have come to be the common citations for defining ABNF. The current document separates out that definition, to permit selective reference. Predictably, it also provides some modifications and enhancements..."
Guidelines for the Use of Formal Languages in IETF Specifications. October 1, 2001. "Formal languages are useful tools for specifying parts of protocols. However, as of today, there exists no well-known language that is able to capture the full syntax and semantics of reasonably rich IETF protocols... Procedural parts of a specification may be written in a pseudo-code which is unambiguously defined in the document. This is clearly a very good way in which to express the algorithm. o Use of a program in any known or intuitive programming language, including pseudo-code, may be used to illustrate and support a specification which is in itself complete. The emphasis when using pseudocode needs to be on clarity..."
Key Words for Use in RFCs to Indicate Requirement Levels. Request for Comments: 2119. "In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. Authors who follow these guidelines should incorporate this phrase near the beginning of their document: The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in RFC 2119..."
- Updated list of IETF tools for spec production, automation, verification. 2005-09.
- Checklist for Internet-Drafts (IDs) Submitted for RFC Publication
- xml2rfc. The xml2rfc tool "will allow you to take your XML source (using the format defined in RFC 2629) and see how the results look like in the original ASCII look-and-feel or the new modern HTML rendition of that look-and-feel." See also the README document.
- 'idnits'. The 'idnits' tool "looks for violations of Section 2.1 and 2.2 of the Checklist requirements. idnits works on Linux, on Windows under Cygwin, on *BSD and may work on Solaris. Testing on *BSD and Solaris has been minimal, though. To install, simply download the script, place it in your path and make it executable. idnits uses awk and sh internally..."
- IETF Applications Area
- IETF XML Directorate. "The XML Directorate provides expert review of the use of XML and XML-related technologies in IETF documents."
- IANA (Internet Assigned Numbers Authority)
- The Internet Engineering Steering Group
- Active IETF Working Groups
- See also from W3C:
- Online Pubrules Checker
- Publication Rules
- Manual to Edit the QA Matrix: use of N3, RDF, XSLT, XHTML.
- Matrix of W3C specifications, produced using RDF, XSLT, and XHTML.
- Automating the Publication of Technical Reports
- Bibliographic data extractor for W3C TR publications
- W3C QA Toolbox: QA Tools, Validators, Tests
- Quality Assurance at W3C